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 athttps://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, and its listread recordsfetchsearchread a recordfetch a pagerun a searchdelete a recordnot on the list: refusedbefore any work, at no chargea key can do only what is on its list
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 athttps://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 problemunauthorized, 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.