Authentication - Symmetry Docs

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 URIs 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:

Sample Request Header

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

Example request

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

cURL

curl --location 'https://api.symmetry.com/authentication/login' \
--header 'Accept: application/json' \
--header 'api-key: YOUR_API_KEY'

Example response

{
  "accessToken": "eyJhbGc1234567890asdfghjklv0I8N-WgO7q23S4"
}

Invalid response

An invalid API key will produce the following response:

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

Embedded experience access

There are three places in the Symmetry I-9 application that require one-time, session-level access for embedded experiences:

Employee embedded experience
Employer administrator embedded experience
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 access, make a GET request to the respective generate endpoint using your API key in the HTTP header. A successful call returns a one-time use URI, which you will use inside your application to launch the embedded mode.

Experience	Endpoint
Employee	`GET /employees/{employeeId}/generateToken`
Employer administrator	`GET /admins/{adminId}/generateToken`
E-Verify settings	`GET /admins/{adminId}/everifySettings/generateEverifySettingsUri`

The two generateToken endpoints return a single embeddedUri with the token already embedded as a query parameter, so one URL both signs the user in and opens their session:

{
  "token": {
    "embeddedUri": "https://example-subdomain.workbright.com/sign_in_with_token?token=26aab821e4536a8695061c79ca577840"
  }
}

The E-Verify settings endpoint instead returns two URIs—authenticateUri to sign the administrator in, and embeddedUri for the page they land on. Open them in that order, or the page will not load. See Configure E-Verify for that flow. The resulting token has a 30 minute expiration and will timeout after 1 hour of inactivity. 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 ••••••'

Deep links into the administrator experience

The administrator endpoint above opens the embedded experience at its default page. Three additional endpoints generate access that lands an administrator on a specific page instead, which is useful when you want to send someone straight to the task they need to complete. Each is scoped to an administrator and returns authenticateUri to sign the user in, plus embeddedUri for the page they arrive on.

Endpoint	Lands on
`GET /admins/{adminId}/generatePendingCountersignUri`	The administrator index, filtered to I-9s awaiting Section 2 verification.
`GET /admins/{adminId}/everifyCases/generateUri`	The E-Verify case index.
`GET /admins/{adminId}/everifyCases/{id}/generateUri`	A specific E-Verify case.
`GET /admins/{adminId}/employees/{employeeId}/submissions/{submissionId}/generateUri`	An individual employee’s submission page.

API domain

There is one API domain (apiDomain) for all Symmetry I-9 endpoints:

Production: https://api.symmetry.com/i9

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.

​API key

​Sample header

​Example request

​Example response

​Invalid response

​Embedded experience access

​Example request

​Deep links into the administrator experience

​API domain

​API versioning

API key

Sample header

Example request

Example response

Invalid response

Embedded experience access

Example request

Deep links into the administrator experience

API domain

API versioning