Authentication & API Tokens

All API endpoints require valid authentication to allow access. How you get a company's API token depends on how you use Everee:

• Payroll Infrastructure: you drive everything through the API, and there is no admin portal for your customers. The company's API token is returned once, in the response that creates the company. See Creating and completing a company.
• Hosted payroll: an administrator creates and manages API tokens inside the Everee admin portal.

❗️

API tokens are not publishable

Everee API keys are sensitive system-to-system shared secrets and must not be published in any client-facing codebase. That includes web app code, native mobile app code, and so on.

To integrate a client-facing application with Everee, first secure the API key within your backend systems, then create an API endpoint to securely deliver data to your client-side application.

Creating a token in the admin portal (hosted payroll)

📘

Hosted payroll only

These steps apply to hosted payroll company instances. In Payroll Infrastructure, the company token is returned at company creation and there is no Integrations Hub for your customers.

You can generate an API token in the Integrations Hub section of the Everee web app. Find the section called "Everee API" and click the ➕ icon:

Next, make a note of your instance's "Company tenant ID", and then click "Create API token":

Sending the token

The API token, and the numerical tenant/company ID, must be included in every company-key request using two headers. The x-everee-tenant-id header is required on every request, and a request without it is rejected. Your API token must be sent as an HTTP Basic Authentication header, using the basic scheme:

authorization: basic dHNrX3Byb2Rf...
x-everee-tenant-id: 12345

Your API token is tied to one company instance, and that's what decides which instance a request acts on. Keep sending the matching tenant ID with every request. For a company you created through the Partner Company API, the tenant ID is the company's id, and you can see, add, rotate and retire its API tokens with the Company API keys endpoints.

🚧

Base64-encode the API token

As with any HTTP Basic credential, the value after basic is Base64-encoded. Encode your API token exactly as it was issued, and don't add a password. A trailing colon is optional. Both of these work:

Text

authorization: basic base64(tsk_prod_...)
authorization: basic base64(tsk_prod_...:)

Once an API token has been deleted or rotated, and it has expired, it will no longer be valid for authentication and any requests using that token will respond with an HTTP 401 error.

Token format

A new API token is shown once: in the admin portal when you create it (hosted payroll), or in the response that creates the company (Payroll Infrastructure). Copy it into your secrets manager right away. It can't be shown again, so if you lose it, create a replacement and rotate.

An API token begins with tsk_prod_ for a Production company instance, or tsk_test_ for a Sandbox instance. The full shape is:

<kind>_<mode>_<version digit><16-character key ID><32-character secret>

For example, a Production token looks like tsk_prod_2 followed by 48 letters and numbers, and a Sandbox token looks like tsk_test_2 followed by 48 letters and numbers. The whole token is 58 characters.

Treat the token as an opaque string. Send it exactly as issued, without changing it or its capitalization. Tokens are 58 characters today, but don't validate their length or pattern, and leave room to store at least 128 characters so a future change to the format doesn't break your integration.

ℹ️

Older tokens

Tokens created before this format begin with sk_ and have no environment marker. They keep working, and you handle them in exactly the same way.

Related

• To see what a token has been used for, or which calls are still using one you're about to rotate, filter the Request Log API by api-key-id.
• Each company instance has its own token and tenant ID. See Company instances & multiple EINs.
• Sandbox and Production are separate instances, each with its own token and tenant ID. See Sandbox & Production.
• Requests are rate limited per token. See Rate limits.