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 reads what you can read 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. Every operation in version 1 reads, so a key needs 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.

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.

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.