Authentication

Every request to the cloud parse API carries an API key in the Authorization header:

Authorization: Bearer aff_0123456789abcdef0123456789abcdef01234567

A key looks like aff_ followed by 40 hexadecimal characters. The self-hosted container needs no key at all: it is licensed at the container, so its requests carry no header. See Self-hosted.

Creating a key

Keys are created in the console, on the API keys screen at /keys. Sign in on the host for your region, open that screen and create a key.

Three things to know before you do:

• The key is shown in full exactly once, when it is created. Only a hash of it is stored, so nobody can show it to you again. Copy it into your secret store there and then. If you lose it, revoke it and create another.
• You may hold three keys at a time. That is enough to rotate: create the new key, deploy it, then revoke the old one.
• A key is created from the console only. There is no API for creating keys, so you cannot bootstrap one key with another.

A key can carry an expiry date, which the keys screen shows in its own column. Keys you create there do not expire unless one was set for you. An expired key is rejected exactly like an unknown one.

Scope: what a key can do

A key belongs to a user, not to an organization or a product. Within your region, one key works against both the Resume Parser at resume-parser.affinda.com and the wider Affinda platform at app.affinda.com. Treat it as a credential for your whole account, and store it accordingly.

Which organization pays for a parse is decided separately. If your account has exactly one Resume Parser organization, which is the usual case, you can leave it alone. If it has more than one, pass ?organization=<identifier> and the request says which one is charged. Without it, a request from a multi-organization account is answered 400 organization_required, rather than the charge being guessed. See the API reference.

Keys are bound to their region

The three regional hosts are three separate deployments, each with its own database. A key exists in the region it was created in and nowhere else, so a key created on resume-parser.eu1.affinda.com does not authenticate against resume-parser.affinda.com. It is not a different error either: the other region has never seen that key, so it answers 401 unauthorized, exactly as it would for a made-up one.

If a valid-looking key returns 401, check the host before you check the key. See Regions.

Do not call the API from a browser

Anything running in a browser hands its API key to whoever opens the developer tools, and the key works against your whole Affinda account. Call the parse API from your server, and let your own frontend talk to your own backend.

When authentication fails

The body is this API's flat envelope, for example:

{"error": "Invalid token.", "code": "unauthorized"}

Errors and limits covers the envelope and the rest of the codes.