Skip to main content
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 uuid 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. 
{
  "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": "http://{{host}}/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. 
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. 
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. 
{
  "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. 
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