On receiving API access, API user receives a secret token which is unique to their account. This token is used in requests to authenticate the user.
Secret token is added to the URL query parameters
curl "https://api.com/account?token=${TOKEN}"
> {"id":12345,...}
Querystring-based usage of tokens is generally more insecure because of the possibility of systems logging the entire request URL including the token into a logging system which may not be secure
Secret token is added as a HTTP header
curl -H "X-Auth: ${TOKEN}" https://api.com/account
> {"id":12345,...}
Secret token is sent in the request body
curl -d '{"token":"eYabcd",...}' "https://api.com/account"
Similar in concept with Secret Token, but user receives a Refresh Token which is used to request for a Secret Token instead of being used directly.
This pattern improves security because if the Secret Token was leaked, it will not be valid forever to an attacker. The API consumer should handle the token renewal mechanism from a secure environment.
curl -H "X-Refresh: ${REFRESH_TOKEN}" "https://api.com/token"
> {"token":"xyzabc","refresh_token":"defghi","expires_at":"2020-12-30T14:00:00+0800"...}
curl -H "X-Auth: ${TOKEN}" https://api.com/account
> {"id":12345,...}
OAuth is more commonly used in systems that enable an API consumer to perform actions on behalf of a user.
- Direct user to an authentication page
- Receive an authorization code after user authorizes API consumer
- Exchange authorization code for an authentication token (either a Secret Token or a Refresh Token)
- Use token to perform actions on behalf of another user
- On receiving API access, user receives an SSL certificate
- User uses SSL certificate whenever they access the service
- User should only perform subsequent access to the service from the machine they used to register
- User has technical expertise with managing their own SSL certificates
- Inter-service communication (aka mTLS in cloud-native systems)