AUTH

Token Controller

September 2, 2024 May 7, 2025

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
FieldTypeRequiredDescription
client_idstring✓Unique identifier for the application requesting authentication.
devicestring✗Unique identifier for the device initiating the authentication request. Useful for multi-device session management.
iframeboolean✗Flag indicating if authentication flow runs within an iFrame. Affects UI/UX and security considerations.
statestring✓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!

Invalid API documentation data

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
FieldTypeRequiredDescription
resourcestring✗Target resource identifier for which the access token is being requested. Helps in resource-specific token issuance.
Response
FieldTypeDescription
ac:sessionobjectDetailed session information
    └ userobjectUser infos
        └ idintegerIdentifier of the currently logged in user
        └ firstnamestringFirstname of the currently logged in user
        └ lastnamestringLastname of the currently logged in user
        └ emailemailE-Mail address of the currently logged in user
        └ customerIdintegerIdentifier of the customer
    └ customerobjectCustomer info
        └ idintegerIdentifier of the customer
activebooleanIf true, the current token is active/valid
client_idstringUnique identifier for the application requesting authentication.
expintegerUnix timestamp (seconds since epoch) when the access token will expire.
token_typestringThe 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
Related Articles