Authentication

Overview⁠

Every request carries a personal API key. The key says who is calling, and the API answers with what that person can read. Create and revoke keys under Settings → Security & access → Personal API keys.

The key format⁠

A key is 46 characters: attia_api_, 30 random letters and digits, then a 6-character checksum.

attia_api_ + 30 random characters + 6-character checksum

The checksum is a CRC-32 of the 40 characters before it. The API checks the prefix and the checksum before it looks the key up, so a mistyped key gets invalid-api-key at once. The fixed prefix and the checksum also let a secret scanner recognise a key that leaked into code or a log.

Attia stores a hash of the key, never the key. The key list shows only its first characters, so copy the key when Attia shows it after you create it.

Send the key⁠

Send the key in the Authorization header as a bearer token. The bare key without Bearer works too.

curl https://attia.app/api/v1/jobs \  -H "Authorization: Bearer $ATTIA_API_KEY"

A request with no key gets invalid-api-key with status 401 and a WWW-Authenticate: Bearer header.

Call the API from a server or a script, never from a web page. The API refuses a call from a web browser with browser-not-allowed before it reads the key, and it sends no CORS headers. A key belongs on a server: a key in page source is a key anyone can copy.

Permissions⁠

A key acts as you. It can do what you can do in the workspace, and never more. When you create it, you narrow it further.

• Permissions: Full access, or a choice of Read, Write and Admin. While an admin has turned on Candidate data in the API in Settings → API, an admin can also choose Read candidate data and Write candidate data. Full access never includes those two, and turning the switch off removes them from every key. Reading jobs needs Read, and creating a job needs Write. Subscribing to a webhook needs Admin, and works only while the key's member is a workspace admin. The applications and candidates operations need Read candidate data, which the API names candidates:read.
• Team access: every team you have access to, or only the teams you pick. A key limited to some teams returns only jobs that at least one of those teams has access to, only applications in those teams, and only candidates with an application on one of those teams.

A valid key without the permission an operation needs gets insufficient-scope.

Revoke a key⁠

Use Revoke API key in the key's menu under Settings → Security & access → Personal API keys. The key stops working at once, and the next request with it gets invalid-api-key.

A key also stops working when you leave the workspace or the workspace is deleted. The API answers those the same way, so a client cannot tell a revoked key from one that never existed.

When GitHub secret scanning finds an Attia key in a public repository, Attia revokes the key at once and emails the person who created it, if they are still a member of the workspace, even if they turned emails off. The email names the key and where it was found. The audit log records it as Revoked leaked API key.

Expiry⁠

A key you create in Settings has no expiry date and works until it is revoked. A key past its expiry date gets invalid-api-key, as a revoked key does.

IP restrictions⁠

If your workspace restricts access by IP address, the same list applies to API calls. A call from another address gets ip-not-allowed. Workspace owners are exempt, as they are in the app.