Skip to content

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

Authorization: Key YOUR_API_KEY_HERE
Content-Type: application/json

Body

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
}

Response

200 — application/json

{
"token": "your.jwt.token"
}

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

Authorization: Key YOUR_API_KEY_HERE
Content-Type: application/json

Body

{
    "token": "your.jwt.token"
}

Response

200 — application/json

{
"token": "your.jwt.token"
}

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.

Request

Headers

Authorization: Key YOUR_API_KEY_HERE
Content-Type: application/json

Body

{
    "token": "your.jwt.token"
}

Response

200 — application/json

{
"token": "your.new_jwt.token"
}