Skip to content
Connect2id

Authorisation store

1. Introduction

The Connect2id server has a dedicated API and store to keep track of the authorisations that are associated with each issued access and refresh token.

A new authorisation object is implicitly created when an OpenID Connect authentication request is served through the authorisation session API, or when the direct authorisation API is invoked. Each authorisation is uniquely keyed by the combination of its subject and client identifiers.

A RESTful web API is provided to enable inspection, update or revocation of the issued authorisations:

  • Inspect and update an individual authorisation.
  • List the subjects and clients with authorisations.
  • List all authorisations for a particular subject or client.
  • Revoke an authorisation and associated tokens.

The web API may also be used to create new authorisations and tokens directly, bypassing the intended APIs for that mentioned above. This could for instance be used to pre-load the Connect2id server with a batch of ready authorisations as part of a new deployment or migration procedure.

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/v2/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 the OAuth 2.0 code flow. The authorisation code will expire according to the configured lifetime.

The return=tokens query parameter causes an access and refresh token pair to be returned instead. This is intended for use in the 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 attribute of the authorisation.

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 refresh token pair to be returned (for OAuth 2.0 implicit flow). If omitted or set to another value causes an authorisation code to be returned (default behaviour, for OAuth 2.0 code flow).

Body:

Success:

  • Code: 200

  • Content-Type: text/plain when the returned content is an authorisation code (implicit OAuth 2.0 flow), or application/json when the returned content is 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 (implies OAuth 2.0 code flow):

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

{
  "sub" : "alice",
  "cid" : "65564eb0058d",
  "scp" : [ "openid", "email", "app:write" ],
  "rur" : "https://client.example.com/in",
  "lng" : true,
  "irt" : true,
  "iss" : "http://server.example.com",
  "iat" : 1360050795,
  "aud" : [ "https://resource-1.example.com", "https://resource-2.example.com" ],
  "idt" : "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...",
  "clm" : [ "sub", "name", "email", "email_verified" ]
}

The resulting response, containing the authorisation code string:

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

17fff8b14f7c

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 given token lifetime (as specified by the atl attribute of the authorisation object.

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/v2/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": "b15b843981cf",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope": "openid email profile app:write"
}

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 access token lifetime atl attribute of the authorisation object. The refresh token remains unchanged.

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/v2/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": "b15b843981cf",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope": "openid email profile app:write"
}

3.1.4 POST – import authorisation record

Imports an authorisation record from another Connect2id server. Introduced in Connect2id server v6.6.

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/v2/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

Returns one or more authorisations, optionally matching the specified query parameters.

Hints:

  • Use subject or client_id on their own to get all long-lived authorisations for a given user, or client application.

  • 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. Not required when direct access token inspection is enabled.

  • [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 application (produces a 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 application (produces a 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 application (produces a 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/v2/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", "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" ]
}

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

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

Example response, the act parameter indicates the authorised actor:

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

{
 "sub" : "alice",
 "act" : { "sub" : "admin" },
 "cid" : "65564eb0058d",
 "scp" : [ "openid", "email", "app:write" ],
 "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 user alice and client ID 65564eb0058d:

PUT /authz-store/rest/v2/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/v2/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 enabled.

  • 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. Produces a 404 if the code is invalid / expired. Must not be used together with another form parameter.

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

  • [ refresh_token ] The refresh token to inspect. Produces a 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 encoded JWT claims will be returned.

Errors:

Example request to inspect a self-contained access token:

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

access_token=eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...

Example response detailing the JWT claims if the self-contained access token is valid:

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/v2/revocation

3.3.1 POST

Revokes one or more authorisations and any linked access and refresh tokens.

The revocation is specified by access token, by refresh token, by subject and / or client identifier.

This call is modelled after the standard client-facing token revocation endpoint, but instead of an empty body it returns the authorisation details of the revoked token(s).

Subsequent inspections of matching access tokens (JWT-encoded as well as identifier-based) and refresh tokens will return a 404 status code, indicating the token is invalid or expired.

Hints:

  • Use the access_token or refresh_token parameter to revoke the long-lived authorisation for a given token.

  • Use subject together with client_id to revoke the long-lived authorisation for a given user and client application.

  • Use subject, actor and client_id together to revoke a long-lived impersonated or delegated authorisation.

  • Use subject, actor or client_id on their own to revoke all long-lived authorisations for a given user, actor (in impersonation and delegation cases) or client application.

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:

  • [ access_token ] Revokes the authorisation (short or long-lived) for the specified access token. Produces a 404 if not found, or if the access token is invalid / expired / revoked. Must not be used together with another form parameter.

  • [ refresh_token ] Revokes the authorisation (long-lived) for the specified refresh token. Produces a 404 if not found, or the refresh token is invalid / revoked. Must not be used together with another form parameter.

  • [ subject ] Revokes the long-lived authorisations for the specified subject. Can be combined with the client_id query parameter to revoke the authorisation for a given subject and client application (produces a 404 if not found).

  • [ actor ] Revokes the long-lived impersonated and delegated authorisations for the specified actor. Can be combined with the subject and client_id query parameters to revoke the authorisation for a given subject, actor and client application (produces a 404 if not found).

  • [ client_id ] Revokes the long-lived authorisations for the specified client. Can be combined with the subject query parameter to revoke the authorisation for a given subject and client application (produces a 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 revoked authorization.

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

Errors:

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

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

subject=alice&client_id=1d6a3150fd3c

Example response with the successfully revoked authorisation:

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/v2/subjects

3.4.1 GET

Returns the indexed subjects of all stored 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 stripped from the returned JSON array. The default value is false as this may potentially 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/v2/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/v2/actors

3.5.1 GET

Returns the indexed actors (in impersonation and delegation cases) of all stored 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 this may potentially 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/v2/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/v2/clients

3.6.1 GET

Returns the indexed clients of all stored 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 this may potentially 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/v2/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/v2/authorization-codes

3.7.1 GET

Returns 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/v2/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/v2/refresh-tokens

3.8.1 GET

Returns the current refresh tokens.

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, empty array if none.

Errors:

Example request:

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

Example response:

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

[
  "YWxp.MTIz.G_VFbEPOGTCipUlcWhXf4w",
  "Ym9i.MjM0.gWO1BNJDBKCAdLGPRd80sg",
  "Y2xh.MjM0.cOlzkAVRsAc0dP9xf2-ccQ"
]

3.9 /authz-store/rest/v2/config

3.9.1 GET

Returns the public configuration of the authorisation store.

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.

Errors:

Example request:

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

Example response:

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

{
  "webAPIEnabled" : true,
  "code"          : { "lifetime": 600 },
  "accessToken"   : { "jwsAlgorithm"          : "RS256",
                      "lifetime"              : 600,
                      "selfContainedClaims"   : [ "sub", "cid",  "scp", "exp", "aud", "iss", "iat" ],
                      "jtiByteLength"         : 8,
                      "defaultType"           : "IDENTIFIER",
                      "allowDirectInspection" : true },
  "options"       : { "highlyAvailableMode"   : true }
}

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 (the user identifier). This is a mandatory attribute.

  • cid {string} The identifier of the authorised client (client_id). This is a mandatory attribute.

  • [ scp ] {string array} The authorisation scope. Represented as a JSON array of the individual scope values, omitted if not specified. OpenID Connect authorisations must 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 authorisation flag. If true identifies a long-lived authorisation that is persisted and may optionally allow issue of a refresh token. If false the authorisation is transient and will be deleted as soon as the access token associated with it expires. Defaults to false if not specified for a new authorisation.

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

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

  • [ irt = false ] {true|false} Issue-refresh-token flag. Applies only to long-lived (persisted) authorisations. If true a refresh token will be issued along with the access token. Defaults to false if not specified for a new authorisation.

  • [ rft ] {string} Refresh token. Records the generated refresh token if the issue-refresh-token (irt) flag is true. This attribute is optional and read-only; it must not be set by the API client.

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

  • [ rtl = 0 ] {string} Refresh token lifetime, in seconds. Defaults to zero, which implies the refresh token is permanent (no expiration).

  • [ atl ] {integer} Access token lifetime, in seconds. Defaults to the configured access token lifetime if not specified when a new authorisation is created.

  • [ ate = “SELF_CONTAINED” ] {“IDENTIFIER”|“SELF_CONTAINED”} Access token encoding. Defaults to self-contained (JWT-encoded). If set to IDENTIFIER the issued access token is a secure identifier; the associated authorisation can be looked up by a web API call to the authorisation store. If set to SELF_CONTAINED the issued access token is self-contained; the associated authorisation is encoded in the access token itself, as a signed JSON Web Token (JWT); it can still be inspected by web API call to the authorisation store.

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

  • [ iss ] {string} The issuer identifier of the OAuth 2.0 authorisation server / the OpenID Connect provider. This attribute is optional.

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

  • [ uat ] {integer} The updated-at timestamp. The time of the last authorisation update, as number of seconds since the Unix epoch. This attribute is optional and read-only; it must not be set by the API client.

  • [ aud ] {string array} The authorisation audience. Represented as a JSON array containing one or more client identifiers. This attribute is 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).

  • [ clm ] {string array} The consented claim names, with optional RFC 5646 language tags. This attribute applies to OpenID Connect authorisations only and is optional.

  • [ cls ] {string array} The saved consented claim names from previous authorisations. This attribute applies to OpenID Connect authorisations only and is optional.

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

  • [ cld ] {object} A 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} A JSON object containing preset claims for release at the UserInfo endpoint. This attribute applies to OpenID Connect authorisations only and is optional.

  • [ 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} A JSON object containing optional authorisation data. This attribute is optional.

Example of a persisted (long-lived) 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 the OAuth 2.0 standard, see RFC 6749.

JSON object members:

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

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"
}

4.3 Public configuration

The public configuration parameters of the authorisation store.

JSON object members:

  • webAPIEnabled {true|false} Indicates whether the web API of the authorisation store is enabled

  • code {object} A JSON object containing the configured authorisation code preferences:

    • lifetime {integer} The authorisation code lifetime in seconds.

  • accessToken {object} A JSON object containing the configured access token preferences:

    • defaultLifetime {integer} The default access token lifetime in seconds. Can be overridden by individual authorisations.

    • jwsAlgorithm {string} The JWS algorithm for signing self-contained (JWT-encoded) access tokens.

    • jweAlgorithm {string} The JWE algorithm for encrypting self-contained (JWT-encoded) access tokens.

    • jweMethod {string} The JWE method for encrypting self-contained (JWT-encoded) access tokens.

    • selfContainedClaims {array} The authorisation attributes (or JWT claims) to include in the self-contained access tokens.

    • jtiByteLength {integer} The preferred byte length of JWT identifiers in the self-contained access tokens.

    • allowDirectInspection {true|false} Indicates whether clients can inspect individual access tokens without presenting the master Bearer access token to the authorisation store web API.

  • options {object} A JSON object containing other configuration settings:

Example public configuration JSON object:

{
  "webAPIEnabled" : true,
  "code"          : { "lifetime": 600 },
  "accessToken"   : { "defaultLifetime"       : 600,
                      "jwsAlgorithm"          : "RS256",
                      "jweAlgorithm"          : "dir",
                      "jweMethod"             : "A128GCM",
                      "selfContainedClaims"   : [ "sub", "cid",  "scp", "exp", "aud", "iss", "iat" ],
                      "jtiByteLength"         : 8,
                      "defaultType"           : "IDENTIFIER",
                      "allowDirectInspection" : true },
  "options"       : { "highlyAvailableMode" : true,
                      "preloadCache"        : false }
}

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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Something bad happened",
  "stack"             : "Exception in thread...",
  "note"              : "See the server logs for additional details"
}