Authorisation store API

1. Introduction

The Connect2id server contains an authorisation store to keep track of the issued OAuth 2.0 / OpenID Connect authorisations and their associated codes, access and refresh tokens.

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.

The authorisation store has a RESTful web API providing a rich set of methods to inspect the issued authorisations and modify or revoke them if required:

  • Inspect and update an individual authorisation.
  • List the subjects and clients with authorisations.
  • List all authorisations for a particular subject or client.
  • Revoke an individual access or refresh token, or an entire authorisation.

If needed, the web API can 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

Additional details are found in the authorisation store configuration reference.

2. Web API overview

Resources
Representations Errors

3. Resources

3.1 /authz-store/rest/v1/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.

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/v1/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" : [ "http://app1.example.com", "http://app2.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 an access and optional refresh token. 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 Should be set to application/x-www-form-urlencoded.

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.

Success:

  • Code: 200

  • Content-Type: application/json

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

Errors:

Example request:

POST /authz-store/rest/v1/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 Should be set to application/x-www-form-urlencoded.

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/v1/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 GET

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

Hints:

  • Use the access_token or refresh_token query parameter to get the authorisation for a given token.

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

  • 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:

Query parameters:

  • [ access_token ] Gets 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. If direct access token inspection is enabled the Authorization header is not required and any client in possession of the access token can query the associated authorisation. Must not be used together with another query parameter.

  • [ refresh_token ] Gets the authorisation (always 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 query parameter.

  • [ 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).

  • [ 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).

  • [ code ] Gets the pending authorisation for the specified authorisation code. Produces a 404 if not found, or the authorisation code is invalid. Must not be used together with another query parameter.

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 an access token:

GET /authz-store/rest/v1/authorizations?access_token=b15b843981cf HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response returning an authorisation object:

Status Code: 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" : [ "http://app1.example.com", "http://app2.example.com" ],
 "clm" : [ "name", "email", "email_verified" ]
}

3.1.5 PUT

Updates a long-lived authorisation. This method can be used to modify the scope and claims of an existing authorisation, or other attributes such as the access token lifetime and type.

Header parameters:

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

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

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/v1/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,
 "rft" : "YWxpY2U.NjU1NjRlYjAwNThk.MTIzNDU2Nzg",
 "atl" : 3600,
 "ate" : "IDENTIFIER",
 "iss" : "https://c2id.com",
 "iat" : 1360050795,
 "aud" : [ "http://app1.example.com", "http://app2.example.com" ],
 "clm" : [ "name", "email", "email_verified" ]
}

Example response:

Status Code: 203 No Content

3.1.6 DELETE

Revokes one or more authorisations matching the specified query parameters.

Hints:

  • Use the access_token or refresh_token query parameter to revoke the 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 or client_id on their own to revoke all long-lived authorisations for a given user, or client application.

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

Header parameters:

Query 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 query 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 query 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).

  • [ 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.

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

Errors:

Example request to revoke the authorisation for subject alice and client 1d6a3150fd3c:

DELETE /authz-store/rest/v1/authorizations?subject=alice&client_id=1d6a3150fd3c HTTP/1.1
Host: server.example.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response with the 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" : [ "http://app1.example.com", "http://app2.example.com" ],
 "clm" : [ "name", "email", "email_verified" ]
}

3.2 /authz-store/rest/v1/subjects

3.2.1 GET

Returns the indexed subjects of the stored long-lived authorisations.

Header parameters:

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/v1/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.3 /authz-store/rest/v1/clients

3.3.1 GET

Returns the indexed clients of the stored long-lived authorisations.

Header parameters:

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/v1/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.4 /authz-store/rest/v1/authorization-codes

3.4.1 GET

Returns the current authorisation codes.

Header parameters:

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/v1/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.5 /authz-store/rest/v1/access-tokens

3.5.1 GET

Returns the current access tokens.

Header parameters:

Success:

  • Code: 200

  • Content-Type: application/json

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

Errors:

Example request:

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

Example response:

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

[ 
  "SrPreh3QyqbcpfxkxrNeriPNwCH_6XKO", 
  "q_TFNdgMJQx5L0cB5YCDUnfhOQxr0nbn",
  "aWR7kZMT8a2yLcrRzFawP2ABPO7_hWiG"
]

3.6 /authz-store/rest/v1/access-tokens/{value}

3.6.1 DELETE

Revokes the specified access token. If the associated authorisation is short-lived it will also be revoked, else the authorisation will not be affected.

Path parameters:

  • value {string} The access token value.

Header parameters:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representing the matching authorisation.

Errors:

Example request:

DELETE /authz-store/rest/v1/access-tokens/b15b843981cf HTTP/1.1
Host: server.example.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

3.7 /authz-store/rest/v1/refresh-tokens

3.7.1 GET

Returns the current refresh tokens.

Header parameters:

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/v1/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.8 /authz-store/rest/v1/refresh-tokens/{value}

3.8.1 DELETE

Revokes the specified refresh token. The associated authorisation will not be affected.

Path parameters:

  • value {string} The refresh token value.

Header parameters:

Errors:

Example request:

DELETE /authz-store/rest/v1/refresh-tokens/2a5884775a13 HTTP/1.1
Host: server.example.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

3.9 /authz-store/rest/v1/config

3.9.1 GET

Returns the public configuration of the authorisation store.

Header parameters:

Errors:

Example request:

GET /authz-store/rest/v1/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. This attribute is intended for new authorisations created in the OAuth 2.0 code flow. It is discarded from the authorisation object after the authorisation code is exchanged for an access / ID / refresh token.

  • [ 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.

  • [ 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.

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

  • [ ate ] {"IDENTIFIER"|"SELF_CONTAINED"} Access token encoding. Defaults to the configured access token encoding. 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 looked up a web API call to the authorisation store.

  • [ 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. This attribute is intended for new OpenID Connect authorisations created in the OAuth 2.0 code flow, to provide temporary storage of the ID token until it's exchanged for the authorisation code. The ID token is discarded from the authorisation object after the exchange is completed.

  • [ clm ] {string array} The consented claim names. 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.

  • [ 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.

  • [ dat ] {object} A JSON object containing optional authorisation data. This attribute is optional.

Example of a new OpenID Connect authorisation to add to the store:

{
  "sub" : "alice",
  "cid" : "65564eb0058d",
  "scp" : [ "openid", "email", "app:write" ],
  "rur" : "https://client.example.com/in",
  "lng" : true,
  "irt" : true,
  "atl" : 3600,
  "ate" : "IDENTIFIER",
  "iss" : "http://server.example.com",
  "iat" : 1360050795,
  "aud" : [ "http://app1.example.com", "http://app2.example.com" ],
  "idt" : "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...",
  "clm" : [ "name", "email", "email_verified" ],
  "cls" : [ "address" ],
  "cll" : [ "es-ES", "en-US" ],
  "uip" : { "groups" : [ "admin", "audit" ] },
  "dat" : { "ip" : "192.168.0.1" }
}

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:

    • lifetime {integer} The preferred access token lifetime in seconds. Can be overridden on an individual basis.

    • defaultType {"IDENTIFIER"|"SELF_CONTAINED"} The preferred encoding type of access tokens. Can be overridden on an individual basis.

    • jwsAlgorithm {string} The preferred JWS algorithm for signing self-contained 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"   : {
      "jwsAlgorithm"          : "RS256",
      "lifetime"              : 600,
      "selfContainedClaims"   : [ "sub", "cid",  "scp", "exp", "aud", "iss", "iat" ],
      "jtiByteLength"         : 8,
      "defaultType"           : "IDENTIFIER",
      "allowDirectInspection" : true
  },
  "options"       : {
      "highlyAvailableMode": true
  }
}

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.

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