API_AUTHENTICATION.md

Authentication

Retrieve access token

Issues access and refresh tokens of account. For OAuth2 Client Credentials Grant authentication flow client's credentials are used to identify the subject of authentication. If an account hasn't exit yet it will be created.

NOTE: the operation isn't allowed for disabled accounts

URI

POST /auth/${AUTH_KEY}/token

URI parameters

Name	Type	Default	Description
AUTH_KEY	string	required	Authentication key (follows ${PROTOCOL}.${PROVIDER} convention)

Payload

Name	Type	Default	Description
grant_type	string	required	Always client_credentials
client_token	string	required	Client credentials

Response

Name	Type	Default	Description
access_token	string	required	Used for account identification
refresh_token	string	required	Used to refresh the access token, never expires
expires_in	string	required	Expiration time of access token
token_type	string	required	Always Bearer

Example

## www-form payload
curl -fsSL \
    -XPOST ${ENDPOINT}/auth/oauth2.example/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "grant_type=client_credentials&client_token=${CLIENT_TOKEN}" \
    | jq '.'
 
## JSON payload
curl -fsSL \
    -XPOST ${ENDPOINT}/auth/oauth2.example/token \
    -H 'Content-Type: application/json' \
    -d "{\"grant_type\":\"client_credentials\",\"client_token\":\"${CLIENT_TOKEN}\"}" \
    | jq '.'
 
{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Refresh access token

Issues a new access token of account. A previously issued refresh token is used to identify the subject of authentication.

NOTE: the operation isn't allowed for disabled accounts

URI

POST /accounts/${KEY}/refresh

URI parameters

Name	Type	Default	Description
KEY	string	required	Account identifier or me

Response

Name	Type	Default	Description
access_token	string	required	Used for account identification.
expires_in	string	required	Expiration time of access token
token_type	string	required	Always Bearer

Example

curl -fsSL \
    -XPOST ${ENDPOINT}/accounts/me/refresh \
    -H"Authorization: Bearer ${REFRESH_TOKEN}" \
    | jq '.'
 
{
  "access_token": "eyJhbGci...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Revoke refresh token

Revokes the old refresh token and issues a new one.

NOTE: the operation isn't allowed for disabled accounts

URI

POST /accounts/${KEY}/revoke

URI parameters

Name	Type	Default	Description
KEY	string	required	Account identifier or me

Response

Name	Type	Default	Description
refresh_token	string	required	Used to refresh the access token, never expires

Example

curl -fsSL \
    -XPOST ${ENDPOINT}/accounts/me/revoke \
    -H"Authorization: Bearer ${REFRESH_TOKEN}" \
    | jq '.'
 
{
  "refresh_token": "eyJhbGci..."
}

Add client's identity

Add another client's identity to the account.

NOTE: the operation isn't allowed for disabled accounts

URI

POST /auth/${KEY}/link

URI parameters

Name	Type	Default	Description
KEY	string	required	Account identifier or me

Payload

Name	Type	Default	Description
grant_type	string	required	Always client_credentials
client_token	string	required	Client credentials

Response

Name	Type	Default	Description
id	string	required	Client's identity identifier

Example

## www-form payload
curl -fsSL \
    -XPOST ${ENDPOINT}/auth/oauth2.example/link \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "grant_type=client_credentials&client_token=${CLIENT_TOKEN}" \
    | jq '.'
 
## JSON payload
curl -fsSL \
    -XPOST ${ENDPOINT}/auth/oauth2.example/link \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H 'Content-Type: application/json' \
    -d '{"grant_type":"client_credentials","client_token":"${CLIENT_TOKEN}"}' \
    | jq '.'
 
{
  "id": "oauth2.example.123"
}

List client's identities

Returns list of client's identities previously added to the account.

URI

GET /accounts/${KEY}/auth

URI parameters

Name	Type	Default	Description
KEY	string	required	Account identifier or me

Response

List of client's identities.

Example

curl -fsSL \
    -XGET ${ENDPOINT}/accounts/me/auth \
    -H"Authorization: Bearer ${ACCESS_TOKEN}" \
    | jq '.'

[
  {
    "id": "oauth2.example.123"
  }
]

Delete client's identity

Removes the client's identity.

NOTE: the operation isn't allowed for disabled accounts

URI

DELETE /accounts/${KEY}/auth/${IDENTITY}

URI parameters

Name	Type	Default	Description
KEY	string	required	Account identifier or me
IDENTITY	string	required	Client's identity identifier

Response

Removed client's identity.

Example

curl -fsSL \
    -XDELETE ${ENDPOINT}/accounts/me/auth/oauth2.example.123 \
    -H"Authorization: Bearer ${ACCESS_TOKEN}" \
    | jq '.'

{
  "id": "oauth2.example.123"
}