Rate this page

Access Token Management

Two endpoints are provided for managing access tokens, one for determining the validity of an access token, and one for revoking an access token.

Access token validation

The token validation endpoint, also called the token introspection endpoint, may be used by resource servers or clients to confirm that an access token is valid, or to examine the access token’s claims. The Data Governance Broker’s token validation endpoint is based on the RFC 7662 specification.

Validation request

POST /oauth/validate

Clients must use a Content-Type value of application/x-www-form-urlencoded but do not need to authenticate. The following parameter is provided in the body of the request using form-urlencoding.

Parameter Required? Description
token yes The access token to validate.

Example request:

POST /oauth/validate HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 152
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:443

token=eyJraWQiOiJBY2Nlc3MgVG9rZW4gU2lnbmluZyBLZXkgUGFpciIsImFsZyI6IlJTNTEyIn0.eyJzdWIiOiJVc2Vyc1wvOTkyM2RiYjgtZTdjNi00NjlmLWI3ZGItYWY3OTMxNzc0MDQ0Iiwic2NvcGUiOiJvcGVuaWQgZW1haWwiLCJleHAiOjE0NzUzMzc4NTUsImlhdCI6MTQ3NDkwNTg1NSwiY2xpZW50X2lkIjoidGVzdDEiLCJqdGkiOiJhLnllWGo3USJ9.BCtPo2cBs9ovSOQnAK7nHOQrxgQiD3by82B-Jbz3Adm2Pr9-LcxMBJ0XVDT_w5JkW1tVE4_lfUITr2Zme72xA-7Pr_jAi-IZAbTAryrt80tphWRasNto7zupc7YjX9qXHLJiq_3hqjA5cQshSZevepION5OHHMeu0Sw_lkJVi5vZatZVdes7e28hD8lJmcmQPK6C3Q6MgSzOLs-OyYAdQd7nUjkigrLpke0OzDsAygAkBU4VIPm2Jn5db7KkjJ3H0BCekRqY8E2e4mbGf0ltlxTOqc7uaMPDt8YNVnFjv8_IY16GzFc1lx9-SOMGy8kSqg5A8jTRhgiDOTzcUtkm7g

Validation response

The response will be a JSON document with an HTTP status of 200. The active field will indicate the validity of the given access token.

Field Type Provided? Description
active boolean always A flag indicating the validity of the access token.
client_id string The client ID of the application to which the token was granted.
exp number An integer timestamp, measured in the number of seconds since January 1, 1970 UTC, which indicates when the token will expire, as defined by RFC 7519.
iat number An integer timestamp, measured in the number of seconds since January 1, 1970 UTC, which indicates when the token was issued, as defined by RFC 7519.
jti string A short unique identifier for the access token, as defined by RFC 7519.
scope string The space-delimited set of access scopes represented by the token.
sub string The unique ID of the user for whom the token was granted. Takes the form of <resource type>/<unique ID>.
token_type string The type of access token. Always has a value of bearer.

Example response for a valid access token:

HTTP/1.1 200 OK
Content-Length: 182
Content-Type: application/json
Date: Mon, 18 Apr 2016 23:36:30 GMT
Pragma: no-cache
Cache-Control: no-store

{
    "active": true, 
    "client_id": "test1", 
    "exp": 1475337855,
    "iat": 1474905855,
    "jti": "a.yeXj7Q",
    "scope": "email openid", 
    "sub": "Users/9923dbb8-e7c6-469f-b7db-af7931774044",
    "token_type": "bearer"
}

Example response for an invalid access token:

HTTP/1.1 200 OK
Content-Length: 16
Content-Type: application/json
Date: Tue, 19 Apr 2016 00:55:43 GMT
Pragma: no-cache
Cache-Control: no-store

{
    "active": false
}

Access token revocation

The token revocation endpoint is used to revoke, or invalidate, a specific access token. The Data Governance Broker’s token revocation endpoint is based on the RFC 7009 specification.

Revocation request

POST /oauth/revoke

Clients must use a Content-Type value of application/x-www-form-urlencoded but do not need to authenticate. The following parameter is provided in the body of the request using form-urlencoding.

Parameter Required? Description
token yes The access token to revoke.

Example request:

POST /oauth/revoke HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 157
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:443

token=eyJraWQiOiJBY2Nlc3MgVG9rZW4gU2lnbmluZyBLZXkgUGFpciIsImFsZyI6IlJTNTEyIn0.eyJzdWIiOiJVc2Vyc1wvOTkyM2RiYjgtZTdjNi00NjlmLWI3ZGItYWY3OTMxNzc0MDQ0Iiwic2NvcGUiOiJvcGVuaWQgZW1haWwiLCJleHAiOjE0NzUzMzc4NTUsImlhdCI6MTQ3NDkwNTg1NSwiY2xpZW50X2lkIjoidGVzdDEiLCJqdGkiOiJhLnllWGo3USJ9.BCtPo2cBs9ovSOQnAK7nHOQrxgQiD3by82B-Jbz3Adm2Pr9-LcxMBJ0XVDT_w5JkW1tVE4_lfUITr2Zme72xA-7Pr_jAi-IZAbTAryrt80tphWRasNto7zupc7YjX9qXHLJiq_3hqjA5cQshSZevepION5OHHMeu0Sw_lkJVi5vZatZVdes7e28hD8lJmcmQPK6C3Q6MgSzOLs-OyYAdQd7nUjkigrLpke0OzDsAygAkBU4VIPm2Jn5db7KkjJ3H0BCekRqY8E2e4mbGf0ltlxTOqc7uaMPDt8YNVnFjv8_IY16GzFc1lx9-SOMGy8kSqg5A8jTRhgiDOTzcUtkm7g

Revocation response

Regardless of the validity of the given token, the response always uses a status code of 200 and contains no body.

HTTP/1.1 200 OK
Content-Length: 0
Date: Tue, 19 Apr 2016 01:05:15 GMT
Pragma: no-cache
Cache-Control: no-store