OAuth tokens

OAuth is an open standard for authorization that allows one application to authorize another to make changes on behalf of an account holder or end user. Access tokens are used to grant permission for applications to access user data for a limited period. Refresh tokens are used to obtain new access tokens without requiring you to authenticate again, extending the session's validity.

Clients

Each OAuth client or application is represented by an M.OAuthClient entity. To register a new client, create a new M.OAuthClient entity with the following properties.

Properties

Description

M.OAuthClient.ClientName

A user-friendly name displayed by the system when asking you to authorize an application.

M.OAuthClient.ClientId

The client's unique identifier.

M.OAuthClient.ClientSecret

A string of printable ASCII characters used by the authorization server to validate requests by comparing the client secret specified in a request with the one specified in the client entity.

M.OAuthClient.RedirectUrl

When a user grants or rejects authorization, the user agent is sent back to the original application using this URL. The redirect URL must be the same as the request URL specified in the client entity.

Making requests

When you have an access token, you can make authenticated requests.

RequestResponse
GET /api/entities/6 HTTP/2
Host: https://<hostname>
Authorization: Bearer CfDJ8CvICaXDq9ZOhEDDMfvIz71_tJhRrMspWLLSht09LtLYeiGPKHBFy3GXjAbArZKIgtYJgT1BoXPzOI2vfHEtN8shpjvgFmVNpRRZ6MjqM4bocXiRnrIRo5k6wbPGItv-BCcwp8n6KRrl3zjuWCiVAESbqh1VipI4HPb99PrgKushTMrytIijF-SjTAmwI5jnizMWM4UahYW0OGkkqhep1ySCeILBB-r2sjs1YuuyDdvgkWeaoLqJmcrP7VkUTsX1tfIf9_7u6CGBLhvn5ZRsyV9kW9gi24OcdXq5Wp5il4rHGclt9JSuAUpZyzbosfzYApgRNvhErJ_-C2VSFL63gl_kPg7CbfGZphOLDQh-GsNomMuWLCw2s5az5BvxpIg2FUZqpadFObIb90mLBNxQl-Nn8BN8g4dXn4elXREXCrcN1j1h2mldpB6rP6N2W-pPS2gaz6qN4svDghBH0DckOj3GshA85yqQwZhYhKrwx8-O_167dEhJZxWQ14hlxllG4e3LDgHsQfcPTfD63klkwgc

The authorization header has the following structure:

RequestResponse
Authorization: Bearer {access_token}

Token lifetimes

Access tokens are valid for one hour, while refresh tokens are valid for 90 days. If you attempt to use an expired access token, you will receive a HTTP 401 response. If you have a valid refresh token, you can use it to generate a new access and refresh token through the refresh token grant, without requiring the participation of the end user. Otherwise, you must use another grant to retrieve a new access and refresh token.

Token lifetimes can be reconfigured through M.Defaults.Json. Token configuration is as follows:

RequestResponse
    "oAuth": {
        "accessTokenLifetime": "01:00:00",
        "refreshTokenLifetime": "90.00:00:00"
    }

Grant flows

The Sitecore Content Hub OAuth 2 implementation supports the following RFC-6749 grant flows:

  • Authorization code  

  • Resource owner password credentials

  • Refresh token

Authorization code grant

The following information is required:

Property

Source

Example value

Client ID

M.OAuthClient entity

MyApplicationId

Client secret

M.OAuthClient entity

MyApplicationSecret

Redirect URL

M.OAuthClient entity

https://myapplication.com

RequestResponse
GET /oauth/authorize?client_id=MyApplicationId&redirect_uri=https%3A%2F%2Fmyapplication.com&response_type=code HTTP/2
Host: https://<hostname>
RequestResponse
HTTP2 302 Found
Location: /en-US/Account?ReturnUrl=%2Foauth%2Fauthorize%3Fclient_id%3DMyApplicationId%26redirect_uri%3Dhttps%253A%252F%252Fmyapplication.com%26response_type%3Dcode

Open the ReturnUrl in your browser and sign in.

RequestResponse
HTTP2 302 Found https://www.myapplication.com/?code=CfDJ8CvICaXDq9ZOhEDDMfvIz71Ai-ImHhlYRsmBv8Qo7tujvkL4FFpjde6jefCIxAutmM_usKnod0eEjzKl78zsxRDYLBb4qa4_eB11E9MqEILH8gigz-GBBhXFKDdj-bB9PZounU-zkEsFFj0abChyb-8AIgCgihLbmZiw4Tbtv1xwtpmDyQ4QR9odgtLOTzQyr-Wu1_Hp3hVymfBS-OWS5PJavzGQ16a4GBlEYX-resh2pDTwJ2oYYUYpy2w1WZIcdvt32_cWsPYWtw9zxZz2_am5mGSADul83PaVTQYtT1deeFOCC1PzudqWw8QeKnB5QX4nVTCy-64b72dtsXk1-7V8ULMMR6sO5Gz5fP_GlEr7nP67AgR2TSFlQekaQFHA_hwpRRaiAcesdLPMP8uQ2V2CnQOTacmUhtiOn_3wWbiYzsjgbQ56EivcbA5vTocWGKGNVE51gv0wkch5apOQjQeCRToI0K-Oa0hadxfw1vNFo3_YxK78zsIDZyjql1Sp6lsCHHjIQhc0SptOuK0WMhsvGytQfgvSthvU-lNCL3A4YOB2pNpIhVd3ERIu2lkzQ1DhUHsg4JQc13FWE8S46NOwccbzMwPvrlEfjFHtP0F_G3vNE9GJeUS48CecAoGT7EoaP76R2fhgZVTvhM3KbQ1l8p1_iBpWcM3y78JF0SJ4T_b2QOjZ9u4If--fbKblsplvee-lTizBr9WAwTTOLfEYqcRFVPYkLu07jdfNt3wjtSRn2V8OtFIEcZZJ2A5VacssNXz0UWOcPJaRJHKm1IDQ36rPyddrEmMTLiSLqZGllskdlVlQhmgqhd_EEuNAmPq-8T0-mCLCHv4LgCJmesTRQou-YI3DctxIdezyHXOrFrZhMYtumk3JEwieGyaj6g

Copy the value of the returned code query parameter, as it is required in the next request.

RequestResponse
POST /oauth/token HTTP/2
Host: https://<hostname>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=CfDJ8CvICaXDq9ZOhEDDMfvIz71Ai-ImHhlYRsmBv8Qo7tujvkL4FFpjde6jefCIxAutmM_usKnod0eEjzKl78zsxRDYLBb4qa4_eB11E9MqEILH8gigz-GBBhXFKDdj-bB9PZounU-zkEsFFj0abChyb-8AIgCgihLbmZiw4Tbtv1xwtpmDyQ4QR9odgtLOTzQyr-Wu1_Hp3hVymfBS-OWS5PJavzGQ16a4GBlEYX-resh2pDTwJ2oYYUYpy2w1WZIcdvt32_cWsPYWtw9zxZz2_am5mGSADul83PaVTQYtT1deeFOCC1PzudqWw8QeKnB5QX4nVTCy-64b72dtsXk1-7V8ULMMR6sO5Gz5fP_GlEr7nP67AgR2TSFlQekaQFHA_hwpRRaiAcesdLPMP8uQ2V2CnQOTacmUhtiOn_3wWbiYzsjgbQ56EivcbA5vTocWGKGNVE51gv0wkch5apOQjQeCRToI0K-Oa0hadxfw1vNFo3_YxK78zsIDZyjql1Sp6lsCHHjIQhc0SptOuK0WMhsvGytQfgvSthvU-lNCL3A4YOB2pNpIhVd3ERIu2lkzQ1DhUHsg4JQc13FWE8S46NOwccbzMwPvrlEfjFHtP0F_G3vNE9GJeUS48CecAoGT7EoaP76R2fhgZVTvhM3KbQ1l8p1_iBpWcM3y78JF0SJ4T_b2QOjZ9u4If--fbKblsplvee-lTizBr9WAwTTOLfEYqcRFVPYkLu07jdfNt3wjtSRn2V8OtFIEcZZJ2A5VacssNXz0UWOcPJaRJHKm1IDQ36rPyddrEmMTLiSLqZGllskdlVlQhmgqhd_EEuNAmPq-8T0-mCLCHv4LgCJmesTRQou-YI3DctxIdezyHXOrFrZhMYtumk3JEwieGyaj6g&redirect_uri=https%3A%2F%2Fmyapplication.com&client_id=MyApplicationId&client_secret=MyApplicationSecret
RequestResponse
HTTP2 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "scope": "offline_access",
    "token_type": "Bearer",
    "access_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz71_tJhRrMspWLLSht09LtLYeiGPKHBFy3GXjAbArZKIgtYJgT1BoXPzOI2vfHEtN8shpjvgFmVNpRRZ6MjqM4bocXiRnrIRo5k6wbPGItv-BCcwp8n6KRrl3zjuWCiVAESbqh1VipI4HPb99PrgKushTMrytIijF-SjTAmwI5jnizMWM4UahYW0OGkkqhep1ySCeILBB-r2sjs1YuuyDdvgkWeaoLqJmcrP7VkUTsX1tfIf9_7u6CGBLhvn5ZRsyV9kW9gi24OcdXq5Wp5il4rHGclt9JSuAUpZyzbosfzYApgRNvhErJ_-C2VSFL63gl_kPg7CbfGZphOLDQh-GsNomMuWLCw2s5az5BvxpIg2FUZqpadFObIb90mLBNxQl-Nn8BN8g4dXn4elXREXCrcN1j1h2mldpB6rP6N2W-pPS2gaz6qN4svDghBH0DckOj3GshA85yqQwZhYhKrwx8-O_167dEhJZxWQ14hlxllG4e3LDgHsQfcPTfD63klkwgc",
    "expires_in": 3600,
    "refresh_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz73OIChE4tuae9LfsM5_0aX8ATs3-paFYvdM7shb5av4wLUZX-fJdhchN7vt2nRhQJRUbRGfKpu6-ksCqBh5fS6PHT3z2ZJ9k27ozmv9uwWYgDIXoL2oeV8afclGqk_qna4JFOcVCe9mMNfL8XbaxybWp9-U1mwIvX6zaf-yfwHQIzd6ctZyGGjUd4lphZ_rahEG4pYq5woqPu7aQV_NaZhpN3tr--ZhRqPDnZBna2mVAfuLd7ZuKct0xwrp9hRmATbE5VYspgn3_XXY0pUA7qZwImqUZD3dvgSViroKVrIPvLKWUbJSAdxqHC8ePbTgGoYvr0ms31bzp4GYZQwAh6D3yr_Oqo2oNPg3KbVYblroRquVEkm5aqGCwPgrJ0LeiR_xbPkmA0UGquGr7FrHg7IU4sa-C5DzqkGjlP4dCW3FL0DqgTR0BLJGyosnA9sjfeOqu_DC626JdwcXOoNdS-XEF1WQGefoOAsQbdP0u1tW5p_1n7a-rDY0Nu3MGVbDc2dXLb00kDUVGd4YGxF0yI139QlU1Hws1tqV1G4Yx25aw77pNFsWsooMQIFHU64CHp8hmmAl-usoDDxiv6cM5XDwf4soYp9VPfMk5CtqAP0iutoIDNmQkd5JcIdhFcmw7aWVLuyLW_uy2kbyiboGmveGckFuNL-TIQlwg5hTI8cjW3UwpioUVx0Xz-R5htVaerCRbhnW1PJtDE7twb2uE-wCeKX2IYFlTdVxmXSYV7orIq5_hBNzfyuKQRF8tWa1e1dNqT8XZd-1JbahvLID_EsuaBDEkzsOGdqYKsze7Cwn5KR_SMLEtVKsfOcL4fBmzKeRYcIA3LsT455B2LTtPjy7"
}

Resource owner password credentials grant

This grant can be used directly as an authorization grant to obtain an access token.

The following information is required:

Property

Source

Example value

Client ID

M.OAuthClient entity

MyApplicationId

Client secret

M.OAuthClient entity

MyApplicationSecret

Username

User

Administrator

Password

User

admin

RequestResponse
POST /oauth/token HTTP/2
Host: https://<hostname>
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=MyApplicationId&client_secret=MyApplicationSecret&username=Administrator&password=admin
RequestResponse
HTTP2 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "scope": "offline_access",
    "token_type": "Bearer",
    "access_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz71_tJhRrMspWLLSht09LtLYeiGPKHBFy3GXjAbArZKIgtYJgT1BoXPzOI2vfHEtN8shpjvgFmVNpRRZ6MjqM4bocXiRnrIRo5k6wbPGItv-BCcwp8n6KRrl3zjuWCiVAESbqh1VipI4HPb99PrgKushTMrytIijF-SjTAmwI5jnizMWM4UahYW0OGkkqhep1ySCeILBB-r2sjs1YuuyDdvgkWeaoLqJmcrP7VkUTsX1tfIf9_7u6CGBLhvn5ZRsyV9kW9gi24OcdXq5Wp5il4rHGclt9JSuAUpZyzbosfzYApgRNvhErJ_-C2VSFL63gl_kPg7CbfGZphOLDQh-GsNomMuWLCw2s5az5BvxpIg2FUZqpadFObIb90mLBNxQl-Nn8BN8g4dXn4elXREXCrcN1j1h2mldpB6rP6N2W-pPS2gaz6qN4svDghBH0DckOj3GshA85yqQwZhYhKrwx8-O_167dEhJZxWQ14hlxllG4e3LDgHsQfcPTfD63klkwgc",
    "expires_in": 3600,
    "refresh_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz73OIChE4tuae9LfsM5_0aX8ATs3-paFYvdM7shb5av4wLUZX-fJdhchN7vt2nRhQJRUbRGfKpu6-ksCqBh5fS6PHT3z2ZJ9k27ozmv9uwWYgDIXoL2oeV8afclGqk_qna4JFOcVCe9mMNfL8XbaxybWp9-U1mwIvX6zaf-yfwHQIzd6ctZyGGjUd4lphZ_rahEG4pYq5woqPu7aQV_NaZhpN3tr--ZhRqPDnZBna2mVAfuLd7ZuKct0xwrp9hRmATbE5VYspgn3_XXY0pUA7qZwImqUZD3dvgSViroKVrIPvLKWUbJSAdxqHC8ePbTgGoYvr0ms31bzp4GYZQwAh6D3yr_Oqo2oNPg3KbVYblroRquVEkm5aqGCwPgrJ0LeiR_xbPkmA0UGquGr7FrHg7IU4sa-C5DzqkGjlP4dCW3FL0DqgTR0BLJGyosnA9sjfeOqu_DC626JdwcXOoNdS-XEF1WQGefoOAsQbdP0u1tW5p_1n7a-rDY0Nu3MGVbDc2dXLb00kDUVGd4YGxF0yI139QlU1Hws1tqV1G4Yx25aw77pNFsWsooMQIFHU64CHp8hmmAl-usoDDxiv6cM5XDwf4soYp9VPfMk5CtqAP0iutoIDNmQkd5JcIdhFcmw7aWVLuyLW_uy2kbyiboGmveGckFuNL-TIQlwg5hTI8cjW3UwpioUVx0Xz-R5htVaerCRbhnW1PJtDE7twb2uE-wCeKX2IYFlTdVxmXSYV7orIq5_hBNzfyuKQRF8tWa1e1dNqT8XZd-1JbahvLID_EsuaBDEkzsOGdqYKsze7Cwn5KR_SMLEtVKsfOcL4fBmzKeRYcIA3LsT455B2LTtPjy7"
}

Refresh token grant

The following information is required:

Property

Source

Example value

Client ID

M.OAuthClient entity

MyApplicationId

Client secret

M.OAuthClient entity

MyApplicationSecret

Refresh Token

Previous OAuth session

CfDJ8...tPjy7

RequestResponse
POST /oauth/token HTTP/2
Host: https://<hostname>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=MyApplicationId&client_secret=MyApplicationSecret&refresh_token=CfDJ8CvICaXDq9ZOhEDDMfvIz73OIChE4tuae9LfsM5_0aX8ATs3-paFYvdM7shb5av4wLUZX-fJdhchN7vt2nRhQJRUbRGfKpu6-ksCqBh5fS6PHT3z2ZJ9k27ozmv9uwWYgDIXoL2oeV8afclGqk_qna4JFOcVCe9mMNfL8XbaxybWp9-U1mwIvX6zaf-yfwHQIzd6ctZyGGjUd4lphZ_rahEG4pYq5woqPu7aQV_NaZhpN3tr--ZhRqPDnZBna2mVAfuLd7ZuKct0xwrp9hRmATbE5VYspgn3_XXY0pUA7qZwImqUZD3dvgSViroKVrIPvLKWUbJSAdxqHC8ePbTgGoYvr0ms31bzp4GYZQwAh6D3yr_Oqo2oNPg3KbVYblroRquVEkm5aqGCwPgrJ0LeiR_xbPkmA0UGquGr7FrHg7IU4sa-C5DzqkGjlP4dCW3FL0DqgTR0BLJGyosnA9sjfeOqu_DC626JdwcXOoNdS-XEF1WQGefoOAsQbdP0u1tW5p_1n7a-rDY0Nu3MGVbDc2dXLb00kDUVGd4YGxF0yI139QlU1Hws1tqV1G4Yx25aw77pNFsWsooMQIFHU64CHp8hmmAl-usoDDxiv6cM5XDwf4soYp9VPfMk5CtqAP0iutoIDNmQkd5JcIdhFcmw7aWVLuyLW_uy2kbyiboGmveGckFuNL-TIQlwg5hTI8cjW3UwpioUVx0Xz-R5htVaerCRbhnW1PJtDE7twb2uE-wCeKX2IYFlTdVxmXSYV7orIq5_hBNzfyuKQRF8tWa1e1dNqT8XZd-1JbahvLID_EsuaBDEkzsOGdqYKsze7Cwn5KR_SMLEtVKsfOcL4fBmzKeRYcIA3LsT455B2LTtPjy7
RequestResponse
HTTP2 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "scope": "offline_access",
    "token_type": "Bearer",
    "access_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz71_tJhRrMspWLLSht09LtLYeiGPKHBFy3GXjAbArZKIgtYJgT1BoXPzOI2vfHEtN8shpjvgFmVNpRRZ6MjqM4bocXiRnrIRo5k6wbPGItv-BCcwp8n6KRrl3zjuWCiVAESbqh1VipI4HPb99PrgKushTMrytIijF-SjTAmwI5jnizMWM4UahYW0OGkkqhep1ySCeILBB-r2sjs1YuuyDdvgkWeaoLqJmcrP7VkUTsX1tfIf9_7u6CGBLhvn5ZRsyV9kW9gi24OcdXq5Wp5il4rHGclt9JSuAUpZyzbosfzYApgRNvhErJ_-C2VSFL63gl_kPg7CbfGZphOLDQh-GsNomMuWLCw2s5az5BvxpIg2FUZqpadFObIb90mLBNxQl-Nn8BN8g4dXn4elXREXCrcN1j1h2mldpB6rP6N2W-pPS2gaz6qN4svDghBH0DckOj3GshA85yqQwZhYhKrwx8-O_167dEhJZxWQ14hlxllG4e3LDgHsQfcPTfD63klkwgc",
    "expires_in": 3600,
    "refresh_token": "CfDJ8CvICaXDq9ZOhEDDMfvIz73OIChE4tuae9LfsM5_0aX8ATs3-paFYvdM7shb5av4wLUZX-fJdhchN7vt2nRhQJRUbRGfKpu6-ksCqBh5fS6PHT3z2ZJ9k27ozmv9uwWYgDIXoL2oeV8afclGqk_qna4JFOcVCe9mMNfL8XbaxybWp9-U1mwIvX6zaf-yfwHQIzd6ctZyGGjUd4lphZ_rahEG4pYq5woqPu7aQV_NaZhpN3tr--ZhRqPDnZBna2mVAfuLd7ZuKct0xwrp9hRmATbE5VYspgn3_XXY0pUA7qZwImqUZD3dvgSViroKVrIPvLKWUbJSAdxqHC8ePbTgGoYvr0ms31bzp4GYZQwAh6D3yr_Oqo2oNPg3KbVYblroRquVEkm5aqGCwPgrJ0LeiR_xbPkmA0UGquGr7FrHg7IU4sa-C5DzqkGjlP4dCW3FL0DqgTR0BLJGyosnA9sjfeOqu_DC626JdwcXOoNdS-XEF1WQGefoOAsQbdP0u1tW5p_1n7a-rDY0Nu3MGVbDc2dXLb00kDUVGd4YGxF0yI139QlU1Hws1tqV1G4Yx25aw77pNFsWsooMQIFHU64CHp8hmmAl-usoDDxiv6cM5XDwf4soYp9VPfMk5CtqAP0iutoIDNmQkd5JcIdhFcmw7aWVLuyLW_uy2kbyiboGmveGckFuNL-TIQlwg5hTI8cjW3UwpioUVx0Xz-R5htVaerCRbhnW1PJtDE7twb2uE-wCeKX2IYFlTdVxmXSYV7orIq5_hBNzfyuKQRF8tWa1e1dNqT8XZd-1JbahvLID_EsuaBDEkzsOGdqYKsze7Cwn5KR_SMLEtVKsfOcL4fBmzKeRYcIA3LsT455B2LTtPjy7"
}

Do you have some feedback for us?

If you have suggestions for improving this article,