Authentication API

This API is used for authenticating clients.
Parameters in this API use snake_case, while the rest of our APIs use camelCase. This is because Oauth2 uses snake case and requires the parameters to be named exactly the same.

Endpoints

Base URL for the Auth API is https://api.unloc.app/auth/v1

POST /token

This endpoint is used for getting an access token. Currently only the client_credentials grant is supported.

Request

Field Optional Type Location Description
grant_type no string body The Oauth2 grant type. Currently only client_credentials is supported.
client_id no string body Id of the authenticating integrator (partner ID)
client_secret no string body Partner API Key
scope yes string or array body Requested scope for the JWT, see Scope. Must be an array of strings or a space-delimited string

Example:

{
    "grant_type": "client_credentials",
    "client_id": "b0bf99dd-f79e-4571-b94b-09f3dd80f8f9",
    "client_secret": "1m1U3zkw6dJdgxspdKOlDrVEDHvrOc8h",
    "scope": "lockHolder.identifier:NO.919424508."

}

Response

200
Field Optional Type Location Description
access_token no string body JWT
token_type no string body What kind of token is returned. Will be bearer for the client_credentials grant
expires_in no number body How long until the provided JWT expires, in seconds. Default is 1 hour
scope yes array body Provided if scope was requested.
lock_holder_id yes string body Id of the lockholder this token is scoped for, if any

Example:

{
    "access_token": "abc.def.ghi",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": [
        "lockHolder.identifier:NO.919424508."
    ],
    "lock_holder_id": "5d7c7d59-dd94-4b0e-8df4-501c028e37ea"
}

4xx

Fields are according to the Oauth2 Documentation

Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error

Example:

{ 
    "error": "invalid_request",
    "error_description": "May not have multiple of the same claim: lockHolder.identifier"
}

Scope

Scope is used to limit the power of an access token.
For security reasons the only way to manage a lock holder is to have a lock holder identifier claim in scope.
It it not possible to have more than one of a given scope.

Supported Claims

lockHolder.identifier:[countryIso].[orgId].[orgIdSuffix]

Necessary for managing a lock holder.
countryIso, orgId and orgIdSuffix are from the lock holder to manage.
See Lock Holders for details