Authentication

Symmetry I-9 supports two types of authentication that are used throughout development: an API key for system-level API access and one-time use access tokens for session-level authorization for the embedded modules.

API Key

To call any endpoint, you must first generate an access token using your Symmetry-provided API key. Include this token as a Bearer token in the Authorization header of your request. Your API key is provided by Symmetry's Client Success Team during onboarding and unique to your company. If you have any questions or are concerned your API key was compromised, please reach out to our team to request a new key.

Sample Header

Below is a sample HTTP header:

curl --location 'https://api.symmetrytest.com/i9/v1/employers' \
--header 'Authorization: Bearer ••••••'

Example Request

Below is a sample cURL to the authorization endpoint to request a token:

curl --location 'https://api.symmetrytest.com/authentication/login' \
--header 'Accept: application/json' \
--header 'api-key: 2318qqxEqU1flcnkK3pgNlDMStza8djMj6cPjaS9p9vejlh'

Example Response

{
  "token": {
    "embeddedUri": "https://symmetry.workbright.com/sign_in_with_token?token=e33b146d43276f00fc781234567890",
    "token": "e33b146d43276f00fc781234567890"
  }
}

Invalid Response

An invalid API key will produce the following response:

{
   "status": "Unauthorized",
   "statusCode": 401,
   "reason": "Api key is invalid and/or expired"
}

Access Tokens

There are three places in the Symmetry I-9 application that require one-time unique access tokens for session-level authorization:

1. Employee embedded experience
2. Employer administrator embedded experience
3. E-Verify settings embedded experience

Session-level access is used for the employee or administrator working in the embedded experience, and not clients accessing the Symmetry API.

To obtain a one-time access token, make a request to the respective /generateToken endpoint using your API key in the HTTP header. A successful call will return a one-time use access token and URI, which you will use inside your application to launch the embedded mode.

• Employee embedded mode access token endpoint: /employees/{employeeId}/generateToken
• Employer Admin embedded mode access token endpoint: /admins/{adminId}/generateToken
• E-Verify settings embedded mode access token endpoint: /admins/{adminId}/everifySettings/generateToken

The resulting token has a 30 minute expiration. Unlike API keys, you may request and use additional access tokens while other access tokens are still active. Therefore, it is not necessary to store the access token in the database if you prefer to request a token just in time before a system request.

Example Request

Below is a sample cURL to establish an employee's I-9 session:

curl --location 'https://api.symmetry.com/i9/v1/employers/12345-b29d-75cf-a308-15ca267af31c/employees/01972151-86d6-7447-aa2a-6a14c063273a/generateToken' \
--header 'Authorization: Bearer ••••••'

API Domain

Below are API domains (apiDomain) for all Symmetry I-9 endpoints:

• Production: https://i9.symmetry.com
• Staging: https://i9-staging.symmetry.com

API Versioning

Currently, Symmetry I-9 is on version 1 (v1), and this version is included in the endpoint URL. Symmetry's API versions are always backwards compatible.