> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate Symmetry I-9 with a system-level API key and one-time access URIs for embedded sessions. Covers request headers, the API domain, and API versioning.

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:

```bash Sample Request Header theme={null}
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:

```bash cURL theme={null}
curl --location 'https://api.symmetry.com/authentication/login' \
--header 'Accept: application/json' \
--header 'api-key: YOUR_API_KEY'
```

#### Example response

```json theme={null}
{
  "accessToken": "eyJhbGc1234567890asdfghjklv0I8N-WgO7q23S4"
}
```

#### Invalid response

An invalid API key will produce the following response:

```json theme={null}
{
   "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:

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

```json theme={null}
{
  "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](/i9/e-verify/configure) 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:

```bash theme={null}
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](/i9/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.