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.

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
/authz-store/rest/v2/authorizations [POST new, exchange, refresh] [GET] [PUT] /authz-store/rest/v2/inspection [POST] /authz-store/rest/v2/revocation [POST] /authz-store/rest/v2/subjects [GET] /authz-store/rest/v2/clients [GET] /authz-store/rest/v2/authorization-codes [GET] /authz-store/rest/v2/refresh-tokens [GET] /authz-store/rest/v2/config [GET]
Representations	Errors
OAuth 2.0 / OpenID Connect authorisation Token response Public configuration	400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error `</ul> </td>`

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.

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:

A JSON object representation of the authorisation to add.

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:

400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error

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" : [ "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 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.

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:

400 Bad Request
404 Not Found – if the code is invalid, the client identifier or redirection URI don’t match, or PKCE verification failed
401 Unauthorized
403 Forbidden
500 Internal Server Error

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

400 Bad Request
400 Not Found – if the refresh token is invalid
401 Unauthorized
403 Forbidden
500 Internal Server Error

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

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

400 Bad Request
400 Not Found – if the refresh token is invalid
401 Unauthorized
403 Forbidden
500 Internal Server Error

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

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

Example response returning an 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" : [ "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:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

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,
 "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 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.

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:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found – indicates the token or code is invalid or expired.
500 Internal Server Error

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" : [ "http://app1.example.com", "http://app2.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 long-lived authorisations 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 returns the authorisation details of the revoked token(s).

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 or client_id on their own to revoke all long-lived authorisations for a given user, 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.

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

400 Bad Request
400 Not Found
401 Unauthorized
403 Forbidden
500 Internal Server Error

Example request to revoke the authorisation for the specified subject and client:

POST /authz-store/rest/v2/authorizations/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" : [ "http://app1.example.com", "http://app2.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.

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:

401 Unauthorized
403 Forbidden
500 Internal Server Error

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

3.5.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.

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:

401 Unauthorized
403 Forbidden
500 Internal Server Error

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.6 /authz-store/rest/v2/authorization-codes

3.6.1 GET

Returns the current authorisation codes.

Header parameters:

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

Success:

Code: 200
Content-Type: application/json
Body: {array} A JSON array of the current authorisation codes, empty array if none.

Errors:

401 Unauthorized
403 Forbidden
500 Internal Server Error

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.7 /authz-store/rest/v2/refresh-tokens

3.7.1 GET

Returns the current refresh tokens.

Header parameters:

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

Success:

Code: 200
Content-Type: application/json
Body: {array} A JSON array of the current refresh tokens, empty array if none.

Errors:

401 Unauthorized
403 Forbidden
500 Internal Server Error

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.8 /authz-store/rest/v2/config

3.8.1 GET

Returns the public configuration of the authorisation store.

Header parameters:

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

Errors:

401 Unauthorized
403 Forbidden
500 Internal Server Error

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.
[ 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.
[ 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. 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.
[ 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 new OpenID Connect authorisation to add to the store:

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:
- highlyAvailableMode {true|false} Indicates whether the highly-available operation mode is enabled.
- preloadCache {true|false} Indicates whether the authorisation cache is preloaded at startup.

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