JSON format to exchange messages with the external management service

To communicate with an external management service, the native OAuth provider prescribes the JSON message format. If the response from the external management system is not in a valid format, you might experience undefined behavior. For example, tokens used more times than expected.

The OAuth provider exchanges messages with the external management service in the following situations.
  • Notify the external service of the existence of generated AZ codes, access tokens, or refresh tokens.
  • Confirm with the external service during validation that AZ codes, access tokens, or refresh tokens are not revoked.
Use the information in the following sections to ensure that your external management service correctly handles these messages.

Notifying when AZ code generated

Sends an HTTP POST request with the following content.
POST
Cache-Control: no-transform 
Content-Type: application/json
{
   "token_type": "az_code",
   "code": "AAJgZEEoYF3el5xjZ_IUp_k6Q... ",
   "scope": "...",
   "client_id": "...",
   "resource_owner": "..."
}

On success, return an HTTP 200 response code. Any other response code is considered an error.

Confirming not revoked when AZ code validated

Sends an HTTP GET request with the following content.
GET
client-id: ...
resource-owner: ...
code: AAJgZEEoYF3el5xjZ_IUp_k6Q...
scope: ...
accept: application/json

On success, return an HTTP 200 response code. Any other response code is considered an error. See Examples of the expected response body for example content for the response body.

Notifying when access token and refresh token generated

Sends an HTTP POST request with the following content. The following material includes content for the refresh token. refresh_token and refresh_token_expires_in are included only when a refresh token is generated.
POST
Cache-Control: no-transform 
Content-Type: application/json
{
    "token_type" : "bearer",
    "access_token" : "AAJgZEEoYF3el5xjZ... ",
    "refresh_token" : "YF3el5xjZ_IUp_k6Q...",
    "scope" : "...",
    "client_id" : "...",
    "resource_owner" : "...",
    "generated" : 1577836800,
    "expires_in" : 3600,
    "refresh_token_expires_in" : 5400
}

On success, return an HTTP 200 response code. Any other response code is considered an error.

Confirming not revoked when access token or refresh token validated

Sends an HTTP GET request with the following content.
GET
client-id: ...
resource-owner: ...
access-token/refresh-token : AAJgZEEoYF3el5xjZ_IUp_k6Q...
scope: ...
accept: application/json

On success, return an HTTP 200 response code. Any other response code is considered an error. See Examples of the expected response body for example content for the response body.

Examples of the expected response body

The response consists of an oauth-revocation section with any of the following combinations.
  • An array of specific tokens.
    { 
   "oauth-revocation" : [
       "AAETb2F1dGgtcmV2...",
       "fZaRlVbnPSc1UGTj..."
   ]
}
  • An array that consists of any combination of owner, application, and before.
    { 
   "oauth-revocation" : [
      {"owner" : "alice"},
      {"owner" : "jane", "before" : 1582052304},
      {"owner" : "joe", "client-id" : "760d..."}           
   ]
}
  • An array of all tokens that match a specific criteria.
    { 
   "oauth-revocation" : [
      {"before" : 1582052304}
    ]
}