Skip to content
Connect2id

Authorisation store

1. Overview

The Connect2id server has a dedicated web API for managing OAuth authorisations and linked tokens:

  • Inspect and update a long-lived authorisation.
  • List the subjects and clients with long-lived authorisations.
  • List the long-lived authorisations for a subject or client.
  • Revoke an authorisation (long-lived or transient) and any associated tokens.

The Connect2id server creates an internal authorisation object for each successful OAuth grant, for example in the code flow through the authorisation session API. Those authorisations flagged as long-lived (with long_lived=true) are persisted and can be inspected or updated via this API.

This web API can also be used to create new authorisations and tokens directly, which can be useful in a OAuth 2.0 server migration.

Access to the authorisation store API is protected by means of a long-lived token. The token must be passed with each HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

More information can be found in the authorisation store configuration reference.

2. Web API overview

Resources
Representations Errors

3. Resources

3.1 /authz-store/rest/v3/authorizations

3.1.1 POST – new authorisation

Adds a new authorisation to the store. If an authorisation with matching subject and client identifiers exists, it will be replaced.

Returns an authorisation code by default, to be exchanged later for an access and refresh token pair. This behaviour is intended for use in a OAuth 2.0 code flow. The authorisation code will expire according to the configured lifetime.

The return=tokens query parameter causes an access and optional refresh token to be returned instead. Intended for use in a OAuth 2.0 implicit flow. The access token will be of type Bearer and will expire according to the configured token lifetime. The issue of a refresh token is controlled by the irt authorisation attribute.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/json.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ return = code ] {“code”|“tokens”} Optional parameter. If set to tokens causes an access and optional refresh token to be returned. If omitted or set to another value causes an authorisation code to be returned.

Body:

Success:

  • Code: 200

  • Content-Type: text/plain when an authorisation code is returned, application/json for a token pair.

  • Body: {string|object} A string representing the authorisation code, or a JSON object representing the token response.

Errors:

Example request to add a new OpenID Connect authorisation for subject alice and client 65564eb0058d and receive an authorisation code for it:

POST /authz-store/rest/v3/authorizations HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub" : "alice",
  "cid" : "65564eb0058d",
  "scp" : [ "openid", "email" ],
  "rur" : "https://client.example.com/in",
  "lng" : true,
  "irt" : true,
  "iat" : 1360050795,
  "idt" : "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...",
  "clm" : [ "sub", "email", "email_verified" ]
}

The resulting response, containing the authorisation code string:

HTTP/1.1 200 OK
Content-Type: text/plain

aeX8cuviKeakieJ7ev7Ohfei2peewoow

3.1.2 POST – exchange authorisation code for token(s)

Exchanges the specified authorisation code for the requested tokens. After the exchange is completed the authorisation code is invalidated. This request is intended for use in the OAuth 2.0 code flow. The access token will be of type Bearer and will expire according to the atl authorisation attribute.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Form parameters:

  • code {string} The authorisation code received when the authorisation was added.
  • client_id {string} The client identifier, corresponding to the cid attribute of the original authorisation.
  • [ redirect_uri ] {string} The redirection URI, corresponding to the rur attribute value of the original authorisation. May be null or omitted only if it’s not specified in the original authorisation.
  • [ code_verifier ] {string} The code verifier for a PKCE request, null or omitted if not required.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representing the token response.

Errors:

Example request:

POST /authz-store/rest/v3/authorizations HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

code=17fff8b14f7c&client_id=65564eb0058d&redirect_uri=https%3A%2F%2Fclient.example.com%2Fin

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token"  : "pha3aisaik3Ohkoneep8ichai8aiwu5j",
  "token_type"    : "Bearer",
  "expires_in"    : 3600,
  "refresh_token" : "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope"         : "openid email"
}

3.1.3 POST – refresh token pair

Refreshes an access token. The old access token will remain valid until it expires. The access token will be of type Bearer and will expire according to the atl authorisation attribute.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Form parameters:

  • refresh_token {string} The refresh token.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representing the token response.

Errors:

Example request:

POST /authz-store/rest/v3/authorizations HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

refresh_token=YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token"  : "pha3aisaik3Ohkoneep8ichai8aiwu5j",
  "token_type"    : "Bearer",
  "expires_in"    : 3600,
  "refresh_token" : "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope"         : "openid email"
}

3.1.4 POST – import authorisation record

Imports an authorisation record from another Connect2id server.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/json.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • import {true|false} Must be set to true.

Body:

Success:

  • Code: 204

Errors:

Example request:

POST /authz-store/rest/v3/authorizations?import=true HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub" : "alice",
  "cid" : "000123",
  "scp" : [ "openid", "email" ],
  "clm" : [ "email_verified", "email" ],
  "iss" : "https://c2id.com",
  "iat" : 1489664026,
  "lng" : true,
  "irt" : true,
  "rft" : "YWxpY2U.MDAwMTIz.bNo1qg74h9wg63cJ_iYfWw",
  "atc" : false,
  "ate" : "SELF_CONTAINED",
  "atl" : 600
}

The response on a successful import:

HTTP/1.1 204 OK

3.1.5 GET

Gets one or multiple long-lived authorisations matching a criteria.

Hints:

  • Use subject with client_id to get the long-lived authorisation for the given end-user and client.

  • Use subject to get the long-lived authorisations for a given end-user.

  • Use client_id to get the long-lived authorisations for a given client.

  • Use the method without query parameters to get all long-lived authorisations (this can be a potentially expensive operation).

Header parameters:

  • [ Authorization ] Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ subject ] Gets the long-lived authorisations for the specified subject, keyed by their client identifier. Returns an empty JSON object if none are found. Can be combined with the client_id query parameter to get the authorisation for a given subject and client (returns 404 if not found).

  • [ actor ] Gets the long-lived impersonated or delegated authorisations for the specified actor. Returns an empty JSON array if none are found. Can be combined with the subject and client_id query parameters to get the impersonated or delegated authorisation for a given subject, actor and client (returns 404 if not found).

  • [ client_id ] Gets the long-lived authorisations for the specified client, keyed by their subject identifier. Returns an empty JSON object if none are found. Can be combined with the subject query parameter to get the authorisation for a given subject and client (returns 404 if not found).

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object|array} The body is a JSON object or array depending on the request query parameters:

    • For requests that resolve to a single authorisation – a JSON object representing the matching authorization.

    • For requests that resolve the authorisations for a given subject or client – a JSON object containing the matching authorizations keyed by their client or subject identifier, or empty JSON object if none.

    • For the request without query parameters – a JSON array of all long-lived authorization objects, empty array if none.

Errors:

Example request to get the authorisation for a specified subject and client:

GET /authz-store/rest/v3/authorizations?subject=alice&client_id=65564eb0058d HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response returning a matching authorisation object:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "sub" : "alice",
 "cid" : "65564eb0058d",
 "scp" : [ "openid", "email" ],
 "scs" : [ "address" ],
 "lng" : true,
 "irt" : true,
 "rft" : "YWxpY2U.NjU1NjRlYjAwNThk.MTIzNDU2Nzg",
 "atl" : 3600,
 "ate" : "IDENTIFIER",
 "iss" : "https://c2id.com",
 "iat" : 1360050795,
 "clm" : [ "email", "email_verified" ]
}

Example request to get an authorisation where admin is impersonating or acting on behalf of user alice for the given client ID:

GET /authz-store/rest/v3/authorizations?subject=alice&actor=admin&client_id=65564eb0058d HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response, the act attribute indicates the authorised actor:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "sub" : "alice",
 "act" : { "sub" : "admin" },
 "cid" : "65564eb0058d",
 "scp" : [ "openid", "email" ],
 "lng" : true,
 "irt" : false,
 "atl" : 3600,
 "ate" : "SELF_CONTAINED",
 "iat" : 1360050795,
 "clm" : [ "name", "email", "email_verified" ]
}

3.1.6 PUT

Updates a long-lived authorisation. This method can be used for the following purposes:

  • To modify the granted scope (scp) and OpenID claims (clm). These will become effective on the next access token issue / refresh. The update will not affect access tokens that are already issued.

  • Modify the access token lifetime (atl, in seconds) and encoding (ate).

  • Enable or disable refresh token issue (irt). Disabling refresh token issue will automatically invalidate the current refresh token if any. Note that setting the refresh token (rft) field has no effect, it is intended only to display the current refresh token for a GET request.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/json.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Body:

  • A JSON object representing the authorisation to update, identified by its subject (sub) and client (cid) attributes.

Success:

  • Code: 204

Errors:

Example request to update the authorisation for end-user alice and client ID 65564eb0058d:

PUT /authz-store/rest/v3/authorizations HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
 "sub" : "alice",
 "cid" : "65564eb0058d",
 "scp" : [ "openid", "email", "app:write" ],
 "scs" : [ "address" ],
 "lng" : true,
 "irt" : true,
 "atl" : 3600,
 "ate" : "IDENTIFIER",
 "iss" : "https://c2id.com",
 "iat" : 1360050795,
 "aud" : [ "https://resource-1.example.com", "https://resource-2.example.com" ],
 "clm" : [ "name", "email", "email_verified" ]
}

Example response indicating success:

HTTP/1.1 203 No Content

3.2 /authz-store/rest/v3/inspection

3.2.1 POST

Inspects an authorisation code, access token or refresh token.

Note: Access tokens can also be inspected at the standard token introspection endpoint.

Header parameters:

  • [ Authorization ] Must specify the configured bearer access token for this web API. Not required when direct access token inspection is allowed.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ revoke = false] {true|false} Facilitates single use of identifier-based access tokens. Causes the access token to be automatically deleted from the store after successful inspection. Has no effect with a self-contained (JWT-encoded) access token.

Form parameters:

  • [ code ] The authorisation code to inspect. Returns 404 if the code is invalid / expired. Must not be used together with another form parameter.

  • [ access_token ] The access token to inspect. Returns 404 if the access token is invalid / expired. Must not be used together with another form parameter.

  • [ refresh_token ] The refresh token to inspect. Returns 404 if the refresh token is invalid / expired. Must not be used together with another form parameter.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representing the matching authorisation. For a self-contained access token only the available encoded JWT claims will be returned.

Errors:

Example request to inspect a self-contained access token:

POST /authz-store/rest/v3/inspection HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

access_token=eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...

Example response containing the available JWT claims for a valid self-contained access token:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "sub" : "alice",
 "cid" : "65564eb0058d",
 "scp" : [ "openid", "email", "app:write" ],
 "iss" : "https://c2id.com",
 "exp" : 1360050795,
 "aud" : [ "https://resource-1.example.com", "https://resource-2.example.com" ]
}

Example error response indicating an invalid or expired access token:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error"             : "invalid_access_token",
  "error_description" : "Invalid / expired access token"
}

3.3 /authz-store/rest/v3/revocation

3.3.1 POST

Revokes authorisations, access and refresh tokens.

The revocation can be specified:

  • by subject and client (with optional actor)
  • by subject to revoke all its tokens and long-lived authorisations for all actors and clients
  • by actor to revoke all its tokens and long-lived authorisations for all subjects and clients
  • by client_id to revoke all its tokens and long-lived authorisations for all subjects and actors
  • by valid access token
  • by valid refresh token

After revocation the inspection of an associated non-expired access token (self-contained or identifier-based) or refresh token will return a 404 status code, indicating the token is invalid. If you experience unexpected timing issues with revocations consider adjusting the authzStore.revocation.checkBias configuration property.

This call mimics the standard OAuth 2.0 client-facing token revocation endpoint. It was modified in Connect2id server 10.0, the older version of the revocation resource is documented in the archive.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ quiet = false ] {true|false} If set to true suppresses output, the response will always be HTTP 204 No Content. Recommended to conserve server and network resources when the revocation is likely to return a large number of authorisations.`

Form parameters:

  • [ subject ] Revokes the tokens and any long-lived authorisations for the specified subject. Can be combined with the client_id query parameter to narrow down the revocation to the specified combination.

  • [ actor ] Revokes the tokens and any long-lived authorisations for the specified actor. Can be combined with the subject and client_id query parameters to narrow down the revocation to the specified combination.

  • [ client_id ] Revokes the tokens and any long-lived authorisations for the specified client. Can be combined with the subject query parameter to narrow down the revocation to the specified combination.

  • [ timestamp ] The revocation timestamp, as number of seconds since the Unix epoch. Accepted when specifying a revocation by subject, client_id and / or actor. Intended for use cases that require exact control over which tokens and authorisations are to be revoked, based on their iat (issued-at time). If omitted the default value is the current time. Since v16.1.

  • [ access_token ] Revokes the tokens and any long-lived authorisation for the subject and client for the specified access token. Returns a 404 if the access token is invalid, expired or revoked. Must not be used together with another form parameter.

  • [ refresh_token ] Revokes the tokens and any long-lived authorisation for the subject and client for the specified refresh token. Returns a 404 if the refresh token is invalid, expired or revoked. Must not be used together with another form parameter.

Success for a given subject and client combination (with optional actor):

  • No long-lived authorisation found or output suppressed with quiet=true:

    • Code: 204

  • Long-lived authorisation found:

    • Code: 200

    • Content-Type: application/json

    • Body: {object} The body is a JSON object representing the revoked long-lived authorisation.

Success for a subject, an actor or a client_id:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} The body is a JSON object containing the revoked long-lived authorisations keyed by their client or subject, or empty JSON object if none were found.

Errors:

Example request to revoke an authorisation for end-user alice and client 1d6a3150fd3c:

POST /authz-store/rest/v3/revocation HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/x-www-form-urlencoded

subject=alice&client_id=1d6a3150fd3c

Example success response, no long-lived authorisation was found:

Status Code: 204 No Content

Example success response, a long-lived authorisation was found and revoked:

Status Code: 200 OK
Content-Type: application/json

{
 "sub" : "alice",
 "cid" : "1d6a3150fd3c",
 "scp" : [ "openid", "email", "app:write" ],
 "scs" : [ "address" ],
 "lng" : true,
 "irt" : true,
 "rft" : "YWxpY2U.NjU1NjRlYjAwNThk.MTIzNDU2Nzg",
 "atl" : 3600,
 "ate" : "IDENTIFIER",
 "iss" : "https://c2id.com",
 "iat" : 1360050795,
 "aud" : [ "https://resource-1.example.com", "https://resource-2.example.com" ],
 "clm" : [ "name", "email", "email_verified" ]
}

3.4 /authz-store/rest/v3/subjects

3.4.1 GET

Gets the indexed subjects of all long-lived authorisations.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ no_duplicates = false ] {true|false} If true duplicate subject entries will be removed from the returned JSON array. The default value is false as deduplication can be an expensive operation.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {array} A JSON array of the indexed subject identifiers, empty array if none.

Errors:

Example request:

GET /authz-store/rest/v3/subjects HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[ "alice", "bob", "claire", "dan" ]

3.5 /authz-store/rest/v3/actors

3.5.1 GET

Gets the indexed actors (in impersonation and delegation cases) of all long-lived authorisations.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ no_duplicates = false ] {true|false} If true duplicate actor entries will be stripped from the returned JSON array. The default value is false as deduplication can be an expensive operation.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {array} A JSON array of the indexed actor identifiers, empty array if none.

Errors:

Example request:

GET /authz-store/rest/v3/actors HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[ "admin-1", "admin-2", "admin-3" ]

3.6 /authz-store/rest/v3/clients

3.6.1 GET

Gets the indexed clients of all long-lived authorisations.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Query parameters:

  • [ no_duplicates = false ] {true|false} If true duplicate client identifier entries will be stripped from the returned JSON array. The default value is false as deduplication can be an expensive operation.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {array} A JSON array of the indexed client identifiers, empty array if none.

Errors:

Example request:

GET /authz-store/rest/v3/clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[ "000123", "000456", "000789" ]

3.7 /authz-store/rest/v3/authorization-codes

3.7.1 GET

Gets the current authorisation codes.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {array} A JSON array of the current authorisation codes, empty array if none.

Errors:

Example request:

GET /authz-store/rest/v3/authorization-codes HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[ "TTKzKw7vuHM", "AAQ4TSxelDU", "Y2d4UbALczU" ]

3.8 /authz-store/rest/v3/refresh-tokens

3.8.1 GET

Gets the current refresh tokens of long-lived (persisted) authorisations. The self-contained refresh tokens of transient authorisations are not tracked and cannot be listed.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • [ Issuer ] The issuer identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {array} A JSON array of the current refresh tokens of long-lived authorisations, empty array if none.

Errors:

Example request:

GET /authz-store/rest/v3/refresh-tokens HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  "KirLfoOzxuZ6eXajXyY_4J3cV3AwxNmF-net-EwVC3qmedyO.jiMQzLJDIZDJGwGSoV976Q",
  "iAhHTb9CId5ERvqvE84X4JEfJM3eMMT_7xB3mmb4Ya6a.J37LSmmdUOCXW4NSyKS7QQ",
  "Yqtf1Eq23L2ca7DJdujgrT6YG3bJEnxsKlCDJY4.1CFlMi1H-Zd7HpW66STUWQ",
]

4. Representations

4.1 OAuth 2.0 / OpenID Connect authorisation

OAuth 2.0 / OpenID Connect authorisation. The subject (sub) and client (cid) attributes are used together as a key to uniquely identify an authorisation and are mandatory. All other attributes are optional when a new authorisation is created.

The scp attribute lists the granted scope values. The clm attribute lists the names of the consented OpenID Connect claims for release at the UserInfo endpoint.

JSON object members:

  • sub {string} The subject (end-user) identifier. Mandatory attribute.

  • cid {string} The identifier of the authorised client (client_id). Mandatory attribute.

  • [ scp ] {string array} The current authorised scope. Represented as a JSON array of the individual scope values, omitted if not specified. OpenID Connect authorisations always include the openid value.

  • [ scs ] {string array} The saved scope values from previous authorisations. Represented as a JSON array of the individual scope values, omitted if none or not specified.

  • [ rur ] {string} The redirection URI of the OAuth 2.0 authorisation / OpenID Connect authentication request. Intended for new authorisations created in the OAuth 2.0 code flow; it is deleted from the authorisation object after the authorisation code is exchanged for the requested token(s).

  • [ lng = false ] {true|false} Long-lived flag. When true the authorisation is long-lived (persisted). When false the authorisation is transient. The default value is false.

  • [ act ] {object} JSON object representing the authorised actor (user) in impersonation and delegation cases:

    * **[ sub ]** {string} The subject (end-user) identifier of the actor.

  • [ irt = false ] {true|false} Issue refresh token flag. When true a refresh token is issued. The default value is false.

  • [ rft ] {string} The refresh token. Omitted if no refresh token is issued. Cannot be set via the API.

  • [ rti ] {integer} The refresh token issue timestamp, as number of seconds since the Unix epoch. Omitted if no refresh token is issued.

  • [ rtl = 0 ] {integer} The remaining refresh token lifetime relative to the refresh token issue timestamp, in seconds. The default value is zero, meaning no lifetime limit.

  • [ rtm = 0 ] {integer} The refresh token maximum idle time, in seconds. The default value is zero, meaning no idle time. Since v15.0.

  • [ rtr ] {true|false} The refresh token rotation setting. Defaults to the configured refresh token rotate setting. Since 14.0.

  • [ atl ] {integer} The access token lifetime, in seconds. Defaults to the configured access token lifetime.

  • [ ate = “SELF_CONTAINED” ] {“SELF_CONTAINED”|“IDENTIFIER”} The access token encoding. When SELF_CONTAINED the token authorisation is encoded in the access token, as a signed and optionally encrypted JSON Web Token (JWT). When IDENTIFIER the issued access token is a secure identifier; the token authorisation can be looked up by making an inspection call. The default value is SELF_CONTAINED.

  • [ atc = false ] Access token encryption setting. Applies only to self-contained (JWT-encoded) access tokens. When true the issued JWT access token will be encrypted with a shared AES key for confidentiality after signing. The default value is false.

  • [ ats = “PUBLIC” ] {“PUBLIC”|“PAIRWISE”} The access token subject type. The default value is PUBLIC.

  • [ iss ] {string} The issuer identifier of the OAuth 2.0 authorisation server / the OpenID provider. Optional.

  • [ iat ] {integer} The issued-at timestamp. The time of the authorisation issue, as number of seconds since the Unix epoch. Optional.

  • [ uat ] {integer} The updated-at timestamp. The time of the last authorisation update, as number of seconds since the Unix epoch. Optional and read-only; must not be set via the API.

  • [ aud ] {string array} The authorised audience. Represented as a JSON array containing one or more identifiers. Optional.

  • [ idt ] {string} The OpenID Connect ID token associated with the authorisation. Intended for new authorisations created in the OAuth 2.0 code flow; it is deleted from the authorisation object after the authorisation code is exchanged for the requested token(s).

  • [ idr = false ] {true|false} The OpenID Connect ID token allow refresh setting. The default value is false. Since 14.0.

  • [ clm ] {string array} The names of the currently consented OpenID claims for release at the UserInfo endpoint, with optional RFC 5646 language tags. Optional, applies only to OpenID Connect authorisations.

  • [ cls ] {string array} The names of consented OpenID claims saved from previous authorisations, including claims already released in a ID token. Optional, applies only to OpenID Connect authorisations.

  • [ cll ] {string array} The preferred claim locales, as RFC 5646 language tags. Optional, applies only to OpenID Connect authorisations.

  • [ cld ] {object} JSON object with optional claims fulfillment data to be passed to the OpenID claims source(s) with access tokens consumed at the UserInfo endpoint.

  • [ uip ] {object} JSON object containing preset claims for release at the UserInfo endpoint. Optional, applies only to OpenID Connect authorisations.

  • [ cch ] {string} The PKCE code challenge associated with the authorisation. Intended for new authorisations created in the OAuth 2.0 code flow; it is deleted from the authorisation object after the authorisation code is exchanged for the requested token(s).

  • [ ccm ] {string} The PKCE code challenge method associated with the authorisation. Intended for new authorisations created in the OAuth 2.0 code flow; it is deleted from the authorisation object after the authorisation code is exchanged for the requested token(s).

  • [ dat ] {object} JSON object containing optional authorisation data. Included as dat claim in access tokens.

Example of a long-lived (persisted) OpenID Connect authorisation for end-user alice and client ID 65564eb0058d for the openid, email and app:write scope values:

{
  "sub" : "alice",
  "cid" : "65564eb0058d",
  "scp" : [ "openid", "email", "app:write" ],
  "lng" : true,
  "irt" : true,
  "atl" : 3600,
  "clm" : [ "name", "email", "email_verified" ]
}

4.2 Token response

Access token response, as specified in OAuth 2.0, see RFC 6749.

JSON object members:

  • access_token {string} The access token. Can be self-contained or identifier-based, depending on the att authorisation attribute.
  • token_type {string} The token type, always set to Bearer. See RFC 6750 for details.
  • expires_in {integer} The access token lifetime, in seconds. The lifetime is controlled by the atl authorisation attribute.
  • [ refresh_token ] {string} The optional refresh token. Refresh token issue is controlled by the irt authorisation attribute.
  • [ id_token ] {string} The optional OpenID Connect ID token. The ID token string is set by the idt authorisation attribute.
  • [ scope ] {string} The authorised scope, if specified by the scp authorisation attribute.

Example token response JSON object:

{
  "access_token"  : "b15b843981cf",
  "token_type"    : "Bearer",
  "expires_in"    : 3600,
  "refresh_token" : "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope"         : "openid email profile app:write"
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing Bearer access token"
}

403 Forbidden

Indicates the web API is disabled.

Example:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error"             : "web_api_disabled",
  "error_description" : "Forbidden: Web API disabled"
}

404 Not Found

The requested resource doesn’t exist. This status code may also indicate the authorisation code or access / refresh token is invalid or has expired in the context of an inspection or revocation request.

Example:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error"             : "authz_not_found",
  "error_description" : "Not found: Authorization not found"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error