Auth service
Our newer APIs use a centralised authentication and authorisation service.
In order to use an API which uses the auth service you must first obtain an API key from the customer control panel. API keys consist of a Key ID and secret, and give access to one or more APIs.
The auth service supports the OAuth2 client credentials protocol.
Using this protocol, API key credentials are submitted to the auth service, which will return a token that can be used in subsequent requests to the API.
Obtaining a token
To use this, make an HTTP POST request to https://auth.mythic-beasts.com/login. The API key credentials should be provided as the HTTP username and password. In addition, provide a grant_type parameter with value client_credentials.
Libraries to perform OAuth2 logins are readily available, but it can also be done using curl:
curl --user $KEY_ID:$SECRET -d grant_type=client_credentials https://auth.mythic-beasts.com/login
$KEY_ID and $SECRET should be the Key ID and secret for your API key
If successful, this will return a 200 response with a JSON body containing a token which can be used in subsequent requests:
{
"access_token": "4kwiV4B4WFuyCXqZ",
"expires_in": 300,
"token_type": "bearer"
}
If unsuccessful, this will return a 4xx response with a JSON body with an error code and description:
{
"error": "invalid_client",
"error_description": "Invalid credentials"
}
Making API requests
This token can be used as an HTTP Bearer authentication token for API requests.
To do this, include it as an HTTP Authorization header prefixed with Bearer.
Again, this can be done using curl:
curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/...
$TOKEN should contain the value of the access_token property returned from
the auth service. The precise URL to use will depend on the API you wish to
access.
Tokens are tied to IP addresses and are only valid if used from the same IP address used to obtain them.
The token will expire after the specified expires_in time (in seconds) after the most recent request using the token. This is technically a deviation from the OAuth2 standard which requires the token to expire the specified period after issue. The auth server behaviour may change to adopt the OAuth2 required behaviour in the future without further notice.
Command line example
Extracting the token from the response can be automated using the jq utility:
KEY_ID=xxx
SECRET=yyy
TOKEN=`curl -s -d 'grant_type=client_credentials' -u "$KEY_ID:$SECRET" https://auth.mythic-beasts.com/login | jq -r .access_token`
curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/...