Authentication
Authenticate API calls with a service token and an Account-ID header. How to get a token, what it can do, and how to rotate it.
Service tokens#
A service token belongs to one EasyEnv user. A call made with it acts as that user, with the access that user has in the account named by the Account-ID header. Send it in the X-Service-Token header:
curl https://api.easyenv.io/v1/accounts/ \
-H "X-Service-Token: $EASYENV_TOKEN"A token does not expire. It works until you generate a new one or delete it, so keep it in a secret store, never in code or in a browser.
Get a token#
- Sign in to the EasyEnv dashboard as the user the integration will act as.
- Open your profile, at
dashboard.easyenv.io/dashboard/profileor from the user menu at the top right, and find theService Tokencard. - Click
Generate tokenand copy it.
[email protected] address, verify its email, and add it to the account as an Admin or Collaborator, and to no other account. Then generate the token as that user, so nothing breaks when a person leaves.Find the account id#
Every other call needs an Account-ID header. List the accounts the token's user belongs to:
curl https://api.easyenv.io/v1/accounts/ \
-H "X-Service-Token: $EASYENV_TOKEN"
# [ { "uuid": "a1b2c3d4", "title": "Acme Engineering", ... } ]Use the uuid of the account as the Account-ID header from then on.
What a token can do#
Exactly what its user can do in the dashboard, no more. For the interview flow that means:
| Field | Type | Description |
|---|---|---|
| List roles and read interviews | Any member of the account. | |
| Invite a candidate | The account owner, an Admin or a Collaborator, whose email address is verified. The account needs an active interview plan with at least one interview left. The plan spends it when the candidate starts, not when you invite, the same as for an invite sent from the dashboard. | |
| Record a decision | The account owner, an Admin or a Collaborator. |
A call without the access it needs gets a 403 whose message says why.
Rotate or revoke#
- Revoke: click
Delete tokenon the Service Token card. Calls with it fail at once. - Rotate: delete it, then generate a new one. The old token stops working the moment the new one exists; there is no overlap, so update your integration right away.
The same two actions are in the API: GET /v1/profiles/me/service-token/?generate=1 returns a new token, and DELETE /v1/profiles/me/service-token/ revokes it. Both accept the service token itself, so whoever holds the token can replace or revoke it, not only its user.
Building for many customers#
If you are building one integration that many EasyEnv customers will use, each customer generates a token in their own EasyEnv account and pastes it, with their account id, into your product. There is no OAuth app flow yet. If that is a blocker for you, tell us.
Tell your customers two things before they paste a token in. The token is not limited to the account they give you: it reaches every EasyEnv account its user belongs to, whatever Account-ID a call names. And whoever holds it can rotate or revoke it with the calls above, which breaks it for everything else that uses it, the CLI included. Both are reasons to generate it as a dedicated user that belongs only to the account your product works with. Your product should never call the rotate or revoke endpoints itself.