Authentication¶
Access to the API is authenticated via the HTTP Authorization header.
Use your Sandbox API Key to authenticate the user via the Auth endpoint. The format for this is: Authorization: Key <your_api_key>.
This will return a JWT Token, which can be used for every subsequent API request in the following format: Authorization: Bearer <your_jwt_token>.
Partner Authentication¶
If you are setup as an Xref partner catering to multiple customers that use Xref, the format for calling Auth endpoint is Authorization: Token <customer_api_key>.
This will also return a JWT Token, which can be used for every subsequent API request in the following format: Authorization: Bearer <your_jwt_token>.
Customers generate their own API key through the Xref Application.
Sandbox API requests behave in the same way as production requests and require you to have Xref credits in your account.
Auth¶
| Method | POST |
| Path | /auth |
This endpoint authenticates a user and returns a JWT token. All API requests other than the auth endpoints must include the JWT token header.
The request body must be a JSON object constructed of the user's first_name, last_name, and email. If a user is not found with the provided email, a new one is created on the fly with the provided first_name and last_name for the account associated with the API Key, and a valid JWT token for that user will be returned.
Please note that the email must have a domain consistent to the company configuration.
If a request is made without the proper headers, the API will return a 401 error. It will return a 400 error if the credentials provided are incorrect, if the email domain if not listed under the configured company domains, or if no email domains are configured for the company.
Request¶
Headers¶
Body¶
Response¶
200 — application/json
Auth Verify¶
| Method | POST |
| Path | /auth/verify |
This endpoint verifies a JWT token. If verification is approved the same JWT token will be returned. The request body must be a JSON object of the token. If a request is made without the proper headers, the API will return a 401 error and, if the JWT token provided is incorrect, it will return a 400 error.
Request¶
Headers¶
Body¶
Response¶
200 — application/json
Auth Refresh¶
| Method | POST |
| Path | /auth/refresh |
This endpoint refreshes a JWT token. It returns a new JWT Token, which is valid for 60 minutes. The request body must be a JSON object of the token.