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.
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:
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:
"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 |
GET /oauth/authorize?client_id=MyApplicationId&redirect_uri=https%3A%2F%2Fmyapplication.com&response_type=code HTTP/2
Host: https://<hostname>
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.
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.
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
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 |
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
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 |
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
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"
}