Token Controller

The Token Controller manages the entire authentication process in our OAuth2-based Auth Server. It provides endpoints for generating authorization codes, exchanging them for access tokens, and validating token validity. All endpoints follow the OAuth2 specification, providing a secure and standards-compliant authentication solution for your applications.”

Reference

Request Code

Generates a short-lived authorization code that must be exchanged for an access token in a subsequent request. This follows the OAuth2 authorization code flow, enhancing security by separating the authorization and token issuance processes.

GET/v4/requestCode

Request Parameters

Field	Type	Required	Description
client_id	string	✓	Unique identifier for the application requesting authentication.
device	string	✗	Unique identifier for the device initiating the authentication request. Useful for multi-device session management.
iframe	boolean	✗	Flag indicating if authentication flow runs within an iFrame. Affects UI/UX and security considerations.
state	string	✓	CSRF protection token to maintain state between request and callback. Should be unpredictable and validated upon return.

Request Token

Exchanges a valid authorization code for a short-lived access token. This endpoint completes the OAuth2 authorization flow and returns comprehensive authentication data including the access token, token type, expiration information, and associated user details. The returned token can be used to authenticate subsequent API requests.

Although currently not marked as such: The redirect_uri is a required field. Applications without redirect_uri will stop working without prior notice soon!

GET/v4/token

Request Parameters

Field	Type	Required	Description
casa	base64	✗	Base64-encoded object containing customer support access information including customerId, userId, and reason for access.
client_id	string	✓	Unique identifier for the application requesting authentication.
code	string	✓	Authorization code received from the Request Code endpoint that will be exchanged for an access token.
device	string	✗	Unique identifier for the device initiating the authentication request. Useful for multi-device session management.
grant_type	string	✓	OAuth2 grant type specifying the authorization flow. Must be "authorization_code" for token requests. ≡ allowed values: authorization_code
redirect_uri	string	✗	URI where the client will receive the authorization response. Must match a pre-registered redirect URI.
resource	string	✗	Target resource identifier for which the access token is being requested. Helps in resource-specific token issuance.
state	string	✗	CSRF protection token to maintain state between request and callback. Should be unpredictable and validated upon return.

Response

Field	Type	Description
accessToken	string	JWT token used to authenticate API requests. Include in Authorization header.
accessTokenExpires	integer	Unix timestamp (seconds since epoch) when the access token will expire.
accessTokenExpiresAt	datetime	ISO 8601 formatted datetime indicating when the access token will expire.
access_token	string	OAuth2 standard access token that can be used for authenticating API requests.
casa	object	Customer Approved Support Access details. Contains information about authorized support access.
└ id	integer	Identifier of the support user who has been granted support access.
client	object	Information about the client application that requested authentication.
└ id	string	Unique identifier of the client application that initiated the authentication flow.
state	string	CSRF protection token to maintain state between request and callback. Should be unpredictable and validated upon return.
tokenType	string	Authentication token type. Always "bearer" for token bearer authentication. Please use token_type instead ≡ allowed values: bearer
token_type	string	OAuth2 standard token type identifier. Always "bearer" for token bearer authentication. ≡ allowed values: bearer
user	object	Authenticated user information including identity and permission details.
└ customerId	integer	Organization identifier associated with the authenticated user.
└ id	integer	Unique user identifier within the system.
└ adminLevel	integer	Administrative permission level of the user (0 for regular users, higher values for administrators).
└ email	email	Primary email address of the authenticated user.

Example Response

{
    "tokenType": "bearer",
    "user": {
        "customerId": 123,
        "id": 123,
        "adminLevel": 0,
        "email": "jane.doe@admiralcloud.com"
    },
    "client": {
        "id": "ae744902-efb2-448a-919d-18b27212aa86"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "accessTokenExpiresAt": "2024-02-22T14:45:23.090Z",
    "accessTokenExpires": 1708609523
  }

Introspect

Validates and introspects tokens according to the OAuth2 specification (RFC 7662). This endpoint allows applications to verify token validity and retrieve metadata about the token including its active status, scope, expiration time, and associated user and customer information. Essential for implementing proper token validation in resource servers.

Please note, that the response code will always be HTTP 200, regardless if the token is active/valid.

POST/v4/oauth2/introspect

Request Parameters

Field	Type	Required	Description
resource	string	✗	Target resource identifier for which the access token is being requested. Helps in resource-specific token issuance.

Response

Field	Type	Description
ac:session	object	Detailed session information
└ user	object	User infos
└ id	integer	Identifier of the currently logged in user
└ firstname	string	Firstname of the currently logged in user
└ lastname	string	Lastname of the currently logged in user
└ email	email	E-Mail address of the currently logged in user
└ customerId	integer	Identifier of the customer
└ customer	object	Customer info
└ id	integer	Identifier of the customer
active	boolean	If true, the current token is active/valid
client_id	string	Unique identifier for the application requesting authentication.
exp	integer	Unix timestamp (seconds since epoch) when the access token will expire.
token_type	string	The token type is Bearer

Check Signed Session | DEPRECATED

Validates cryptographically signed session requests by verifying the authentication metadata. For valid sessions, it returns comprehensive information about the client, user, and customer context. Requires the ‘x-admiralcloud-authmeta’ header containing the HTTP method and path for the signed payload (e.g., ‘post:/v1/userTask’). This endpoint ensures request authenticity for high-security operations.”

You have to send the header “x-admiralcloud-authmeta” that contains the HTTP method and the path for the signed payload, e.g. “post:/v1/userTask”.

POST /v4/checkSignedSession

AUTH

Reference

Request Code

Request Token

Introspect

Check Signed Session | DEPRECATED

Related Articles