Skip to main content
Every call has one header, Authorization, with a bearer credential: an API key, or an access token. The credential says which account the call belongs to and what the call can do.

Send the key

Create an API key at https://app.getclean.ai and put it in the environment variable GETCLEAN_API_KEY. The SDKs read it from there.
get_limits costs nothing and returns what the key can do, so it is a good first call. To give the key in code, pass it as api_key in Python and as apiKey in TypeScript.

Give a key the scopes it needs

A key has a list of scopes, and it can do nothing that is not on the list. A key for an agent that only reads stored records needs one scope, and a stolen copy of it cannot fetch or spend. contents:model depends on the request. A fetch needs it only if the request asks for work by a model: a summary, a schema, or highlights without deterministic_only.

Use an access token for a person

A program that acts for a person can send an access token in place of a key. The token is issued at https://auth.getclean.ai/realms/getclean after the person signs in, and its scopes are the ones that person approved. The steps of the sign-in are at https://auth.getclean.ai/auth.md. A token expires, so the SDKs also take a function in place of the value. The function is called once for each call and returns the current token.
load_token and loadToken are your own functions that return the token your sign-in stored.

Act on a refused credential

A call without a credential that the API accepts returns the problem unauthorized, with the status code 401. Its detail says which of 3 things happened: no credential was sent, the credential is unknown, expired, or revoked, or the credential was put in the address of the request, where it is ignored. A call with a credential that lacks a scope returns the problem insufficient-scope, with the status code 403. This response is cut to the fields that say what to do.
403 Forbidden
scopes_required lists every scope the call needs. For an API key, the owner of the account adds the scope. For an access token, ask the person to approve it. Both refusals come before any work, so nothing is charged. For the other problems, see Errors.

Keep the key on a server

A key is a secret of a server or a program. The API sends no headers that let a web page call it from a browser, so a key that is put into a page fails at once and is not leaked by use. The API takes HTTPS only. A request over plain HTTP is refused and not redirected, so a key and a request body are not sent a second time in the clear.