--- title: "Authentication and keys" description: "How to call the API with a key, what a key may do and how to keep it safe." canonical_url: "https://www.openshield.dev/docs/authentication" --- # Authentication and keys > How to call the API with a key, what a key may do and how to keep it safe. Every request to the checking API carries an API key. Keys belong to an organization, and you create them in the dashboard. ## Sending the key Use either header. They are equivalent. ```bash # The Authorization header curl -H "Authorization: Bearer $OPENSHIELD_API_KEY" ... # The X-Api-Key header curl -H "X-Api-Key: $OPENSHIELD_API_KEY" ... ``` A key looks like `om_live__`: a prefix, 12 characters of id and 32 of secret. The id is not secret: it identifies the key in the dashboard and in the journal. The key is stored only as a hash, so we cannot show it again. The [SightEngine-compatible endpoints](https://www.openshield.dev/docs/migrating-from-sightengine) also take the key in the `api_secret` form field. Never put a key in a query string: the `GET` form refuses it with `key_in_query`, and takes the key in one of the headers above. ## Scopes and workflows When you create a key you choose: - **Scopes**: `image`, `text` or both, and for [fraud prevention](https://www.openshield.dev/docs/fraud-prevention) `fraud` (the whole fraud API) or `fraud_events` (decide and report events only). A key without the scope for a call gets `403 forbidden` for it. - **Workflows**: all of them, or a list. A key limited to some workflows gets `403 forbidden` for any other. - **Expiry**: optional. An expired key gets `401 unauthorized`. Give each service its own key, with the narrowest scope and workflows it needs. ## Editing a key Edit an active key from the dashboard to change its name, scopes, workflows or expiry. The key itself does not change, so servers that use it keep working, and the gateway applies the new access within seconds. A key stays in its environment: a live key cannot become a test key, or the other way round. An expired or revoked key cannot be edited: create a new one. A key a rotation replaced cannot be edited either: it stops at the end of its grace delay, so edit the new key. Owners and admins edit any key; developers edit the keys they created. ## Rotating and revoking - **Rotate** a key from the dashboard to make a new one with the same scopes. The old key keeps working for a grace delay you choose, from 0 to 24 hours, so you can deploy the new one without a gap. - **Revoke** a key to stop it at once. A rotated key in its grace delay counts toward the number of keys your limits allow. ## Key activity and status Open a key's activity from the dashboard to see: - **Right now**: the key's requests this minute, and your organization's requests this minute against its per-minute limit, the checks running at once, and the quota used this period. Limits belong to the organization, so every key shares them. - **Usage**: the key's checks, fraud calls and cost this hour, over the last 24 hours and over the last 30 days. Sandbox calls cost nothing. - **Last calls**: the key's latest checks from the journal, kept as long as your plan's journal retention. Beside its status, the key list flags what needs attention: - **Expires soon**: the key expires within 14 days. - **Grace period**: a rotation replaced the key, and it stops working at the end of its grace delay. - **Never used**: no call has used the key yet. - **Idle 30 days**: the key has not been used for 30 days. Revoke a key you no longer need. ## Keep keys on the server Never put a key in a web page, a mobile app, a browser extension or a repository. Call the API from your backend, and give your front end the decision, not the key. - Store the key in an environment variable or your platform's secret store. The examples in these docs use `OPENSHIELD_API_KEY`. - The API does not answer browser cross-origin requests. A request carrying an `Origin` header gets `403 forbidden`. - If a key leaks, revoke it and create another. The [journal](https://www.openshield.dev/docs/journal-and-ref) shows which key made each check, so you can see what the leaked key was used for. ## Errors
Status error.type When
401 unauthorized The key is missing, malformed, invalid, revoked or expired.
403 forbidden The key may not check this kind of content or use this workflow, or the request came from a browser.
403 organization_suspended An operator suspended the organization. Write to contact@sway.events .
## Sitemap See the full [sitemap](https://www.openshield.dev/sitemap.md) for all pages.