Skip to main content

Authentication

Every request carries an API key, as a bearer token or in an X-API-Key header. Use whichever your HTTP client makes easier.

Authorization: Bearer tf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Read the key from an environment variable. Never paste it into source code.

curl https://api.tarkflo.com/v1/jobs \
-H "Authorization: Bearer $TARKFLO_API_KEY"

A request with no key, a wrong key, an expired key or a revoked key gets 401 invalid_api_key.

Keys act as users​

An API key is an identity for a system, not a person. It acts as a user with a role: the role you choose when you create it, from the same roles you use for your team in Settings, Roles. It has no password and cannot sign in to the dashboard, and it does not use a seat.

In your audit log, a key appears under its name and a service account address, such as sa-9X1v5b1spsA1ZukH@serviceaccount.internal. The address is made when the key is created and never changes, so you can always tell which system did what.

Create one in Settings, API keys:

  1. Choose Create API key.
  2. Give it a name, such as Greenhouse sync.
  3. Choose the role it acts as.
  4. Choose when it expires: no expiry, 1 day, 1 month, 3 months, 6 months, 1 year, or a date of your own.
  5. Copy the key. Tarkflo stores only a hash of it, so it cannot be shown again. Lost keys are replaced, not recovered.

What a key can do​

A key can do what its role can do, with two differences.

  • A key never gets settings, billing, members, roles or API keys, and it cannot delete jobs, candidates or templates, whatever its role allows.
  • A key sees the whole workspace. A person with an assigned-jobs role sees only their own jobs. A key is not assigned to jobs, so it sees them all, within the permissions it holds.

Give each key the least powerful role that does the job. If no role fits, create one in Settings, Roles, such as Integration, with only what that system needs.

EndpointThe role needs
List jobs, Get a job, Get a job's countsjobs:view
List workflows, Get a workflow, List templates, Get a templatetemplates:view
Extract candidate details, Submit candidatescandidates:create
Create an interview, Get a fresh interview linkcandidates:create
Get an interview, Get an interview's reportcandidates:view

A call the role does not allow gets 403 forbidden, and the response names the missing permission in required. Change a role and every key acting as it follows on its next request.

Who can manage keys​

The Owner has API access by default and can grant it to a role in Settings, Roles. Everyone with API access can see every key in the workspace, but can change only the ones they created.

OwnerMember with API accessEveryone else
Create a keyYesYesNo
Give a key a roleAny role except OwnerA role no more powerful than their ownNo
See every key: name, role, creator, last used. Never the secret.YesYesNo
Edit, revoke or delete keys they createdYesYesNo
Do the same for keys other people createdYesNoNo
Grant or remove API access for a roleYesNoNo

Key lifecycle​

  • Revoke stops a key immediately. Its next request gets 401. A revoked key stays in the list, marked revoked, so your records still make sense.
  • Delete removes a key from the list.
  • Expire happens on its own on the date you chose. Choose No expiry for a key that should keep working until you revoke it.

To rotate a key without downtime, create a second key with the same role, deploy it, then revoke the first.

If a key leaks, revoke it first and ask questions afterwards.

Keep keys safe​

  • Use keys from a server only. Never put one in a browser, a mobile app or a public repository.
  • Store keys in an environment variable or a secrets manager.
  • Use one key per integration, so a leak is contained and the audit log tells you which system acted.
  • Choose the least powerful role. A sync that only adds candidates does not need a role that can decide on them.

Every request is written to your workspace audit log under the key's name and its service account address, never the key itself.