Authentication

Every request carries two credentials: an API key and a service credential. The gateway attaches both. Endpoints that act for a signed-in user also need that user's token.

Credentials

Credential	Header	Sent on	Description
API key	x-api-key	Every request	Identifies the calling application
Service credential	Authorization	Every request	Authorizes the calling system
User token	Authorization	User-scoped endpoints	Identifies the signed-in user. Sent with the service credential

Do not put keys, tokens, or account identifiers in this repository. Use placeholders such as NaN and in examples.

User-scoped endpoints

These endpoints take the user from the bearer token, not from the request body:

Endpoint	What it does
Change password	Changes the signed-in user's password
User agreement	Reads or records the signed-in user's agreement

A missing or invalid token returns 401.

Get a user token

1. Call Start login to get the login address. Open it for the user.
2. Call Login authorize with the returned code, or with a username and password. The response has the tokens.
3. Use tokens.access_token on later calls. tokens.expires_in is the number of seconds until it expires.
4. Call Logout with at least one token to end the session. When you send an id token, open the returned logout_url in the browser to finish logout.

Token fields

Field	Type	Description
tokens.access_token	string	Token for later calls
tokens.refresh_token	string	Present when a refresh token was issued
tokens.id_token	string	Present when an id token was issued
tokens.expires_in	number	Seconds until the access token expires
tokens.token_type	string	Usually bearer

Single sign-on accounts

Accounts that use single sign-on cannot change or reset a password through this API. Those calls return 400 with code SSO_ONLY_ACCOUNT.

Authentication errors

Status	Code	When
401		The bearer token is missing or invalid
401		The code, username, or password is not valid on Login authorize
403	ENDUSER_FLOW_MISMATCH	Asurion-enduser does not match the account that owns a reset code
400	SSO_ONLY_ACCOUNT	The account uses single sign-on