API Documentation

First Party Authentication

The most common usage of compliance-auth is to authenticate a user or service directly. To do this, we can use OAuth which provides a standard way to authenticate different user types.

Access Token Resource

The access token resource is a standardised resource that returns information about a newly generated JWT token regardless of whether its for a service or user.

  • Name
    token_type
    Required
    Type
    string
    Description

    The type of token being returned. This will always be Bearer

  • Name
    expires_in
    Required
    Type
    integer
    Description

    The number of seconds until the token expires

  • Name
    access_token
    Required
    Type
    string
    Description

    The encoded JWT token

  • Name
    refresh_token
    Required
    Type
    string
    Description

    The refresh token to be used to generate a new access token after it expires. This is only returned for users.

Access Token Resource

{
    "token_type": "Bearer",
    "expires_in": "31536000",
    "access_token": "jwt.access.token",
    "refresh_token": "reference_token"
}
POST/oauth/token

User Authentication

This endpoint is only suitable for first party authentication. This means, it should only be used by platforms and services we (ITC) own and manage directly. The reason for this is because it relies on the user providing the password. If a third party calls this endpoint, it means the user has had to provide their ITC password, to the third party, and the third party has provided the password to us.

Obviously this means the third party now knows the users password, and we cant be sure they've processed it correctly, that it hasn't ended up in a log file somewhere etc.

If successfully authenticated, a response will be returned which contains the type of token thats returned (will always be Bearer), how long the token is valid for before it expires, the access token and a refresh token.

Required Attributes

  • Name
    grant_type
    Required
    Type
    string
    Description

    Determines the method of authentication used. For user authentication, this must be password

  • Name
    client_id
    Required
    Type
    string
    Description

    ID of the client performing authentication

  • Name
    client_secret
    Required
    Type
    string
    Description

    Secret password of the client performing authentication. This will only be known to the system that makes the authentication request.

  • Name
    username
    Required
    Type
    string
    Description

    The users username which wants to be authenticated

  • Name
    password
    Required
    Type
    string
    Description

    The users password which wants to be authenticated

  • Name
    scope
    Required
    Type
    string
    Description

    A list of space separated scopes that should be attached to the token

Header Parameters

  • Name
    Content-Type
    Required
    Type
    string
    Description

    Should always be set to application/json

  • Name
    Accept
    Required
    Type
    string
    Description

    The OAuth service can return different JWT structures. For the new OAuth structure, you will need to add version=2 or higher. For systems which require the older, deprecated JWT structure that includes dealer and system information encoded within the token, you need to add version=1

Regardless of which version you use in the Accept header, the same JSON response structure will be returned. Only the data encoded in the JWT token will change with different versions.

Request

POST
/oauth/token
use Compliance\Sdk\Authentication\OAuth\Contracts\OAuthSdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private OAuthSdkInterface $sdk;

$response = $this->sdk->v1(new Machine())->issueToken([
    'grant_type' => 'password',
    'client_id' => 'example-client-id',
    'client_secret' => 'example-client-secret',
    'username' => 'john.smith@itccompliance.co.uk',
    'password' => 'secret-password',
    'scope' => 'legacy:autonomy.write legacy.autonomy.read'
], '2.0');

Response

{
    "token_type": "Bearer",
    "expires_in": "31536000",
    "access_token": "jwt.access.token",
    "refresh_token": "reference_token"
}
POST/oauth/token

Service Authentication

The request to authenticate a service is the same as one to authenticate a user, with a few minor changes.

Service access is needed when one API wants to talk to another API. This is useful for scenarios like CRON jobs etc. Service tokens should never be used by users as they generally last longer than user based tokens, and provide greater access.

Because server access tokens don't require a user to enter a username and password, we only need to provide the client ID and secret.

If successfully authenticated, a response will be returned which contains the type of token that's returned (will always be Bearer), how long the token is valid for before it expires and an access token.

Service based tokens responses do not include a refresh token, since there's no user for us to avoid asking for a username and password again from. Instead, when a service based token expires, it should be automatically regenerated by the platform that needs authenticating.

Required Attributes

  • Name
    grant_type
    Required
    Type
    string
    Description

    Determines the method of authentication used. For service authentication, this must be client_credentials

  • Name
    client_id
    Required
    Type
    string
    Description

    ID of the client performing authentication

  • Name
    client_secret
    Required
    Type
    string
    Description

    Secret password of the client performing authentication. This will only be known to the system that makes the authentication request.

  • Name
    scope
    Required
    Type
    string
    Description

    A list of space separated scopes that should be attached to the token

Request

POST
/oauth/token
use Compliance\Sdk\Authentication\OAuth\Contracts\OAuthSdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private OAuthSdkInterface $sdk;

$response = $this->sdk->v1(new Machine())->issueToken([
    'grant_type' => 'client_credentials',
    'client_id' => 'example-client-id',
    'client_secret' => 'example-client-secret',
    'scope' => 'legacy:autonomy.write legacy.autonomy.read'
], '2.0');

Response

{
    "token_type": "Bearer",
    "expires_in": "31536000",
    "access_token": "jwt.access.token"
}