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

# Authentication

> Authenticating with the nmbr API

Nmbr has two categories of tokens that are used throughout development: partner-level tokens (`partner_key`, `partner_secret`) and company-level tokens (`access_token`). You will need to securely manage and store all tokens in your database.

## Partner-Level Tokens

Partner-level tokens are issued to Nmbr partners via the developer portal and grant access to create partner-managed companies.

Using the `partner_secret` you can create a new partner-managed company. In the header of the request you will include the `partner_secret` using an Authorization HTTP header with the bearer token scheme.

```
Content-Type: application/json
Authorization: Bearer ApiTokenAAABBBCCC
```

## Company-Level Tokens

Company-level tokens are scoped for an individual company and are short-lived to improve security practices. The `access_token` can be used to make API requests.

After creation of a partner-managed company, you will receive an `access_token`, `expires_in`, and the `id` of the created company to make subsequent API calls on behalf of the company. `expires_in` is the number of minutes in which the `access_token` will expire.

```json theme={null}
{
  "id": "01hgkpjgyspp2nszf8fq7j9c0a",
  "object": "company",
  "data": {
    "name": "Bobs Burgers",
    "pay_day_movement_setting": "inherit",
    "status": null,
    "created_at": "2023-12-01T22:04:19.000000Z",
    "updated_at": "2023-12-01T22:04:19.000000Z",
    "token": {
      "access_token": "1hucWCMptvpPiO5bbsSwuAGICKeFN8mPdAPWlxYQc3d02eb5",
      "expires_in": 59,
      "expires_at": "2023-12-01T23:04:19.000000Z"
    }
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/companies/01hgkpjgyspp2nszf8fq7j9c0a"
  }
}
```

## Using Access Tokens

You can use `access_tokens` to make requests to the Nmbr API. Use the `access_token` as the Authorization header.

```bash theme={null}
curl --location --request GET 'https://sandbox.nmbr.co/services/payroll/employees' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer AccessTokenAAABBBCCC'
```

## Retrieving new Access Tokens

Access tokens expire 1 hour (60 minutes) after they are issued. If an access token is expired you will receive `401 Unauthorized` errors. To retrieve a new access token, you will need the `company_id` along with the `partner_secret` from the developer portal.

To retrieve your `access_token` use the POST /token endpoint.

```bash theme={null}
curl --location --request POST 'https://sandbox.nmbr.co/services/payroll/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{partner_secret}}' \
--data-raw '{
  "company_id": "{{company_id}}"
}'
```

The corresponding response will include a new `access_token`.

```json theme={null}
{
  "access_token": "28|CO8zAiFQgA15LpDXCgwb5yp5lswJcSJmN82XFG0B9514ee7a",
  "expires_in": 59,
  "expires_at": "2023-12-01T23:07:53.000000Z"
}
```

The `expires_in` value is provided in minutes from when the `access_token` was generated.

## Revoking Access Tokens

If you need to revoke access tokens, you can do so by calling the DELETE /token endpoint.

```bash theme={null}
curl --location --request DELETE 'https://sandbox.nmbr.co/services/payroll/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{partner_secret}}' \
--data-raw '{
  "company_id": "{{company_id}}"
}'
```

This will revoke all access tokens associated with the specified `company_id`.

## Token Management Recommendations

Access tokens are specific to a partner and company. Care should be taken to avoid token refresh race conditions. It is recommended to have unique constraints and when refreshing tokens, lock the associated row.

**Example refresh steps:**

1. An access token needs to be refreshed. We know this because the `expires_in` is less than current time or an HTTP status of 401 is received from a Nmbr API request
2. Lock the `auth_tokens` row for the associated `company_id`
3. Refresh the access token as instructed above
4. Update the `auth_tokens` row with the new access tokens. The `expires_at` should also be updated to x minutes from the current time.
5. Unlock the row
6. Use the new `access_token` for Nmbr API requests
7. All concurrent processes should use the latest `access_token`