Authentication and keys

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.

# The Authorization header
curl -H "Authorization: Bearer $OPENMOD_API_KEY" ...

# The X-Api-Key header
curl -H "X-Api-Key: $OPENMOD_API_KEY" ...

A key looks like om_live_<id>_<secret>: 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 take the key in the api_secret form field (or query parameter, for the GET form) instead.

Scopes and workflows

When you create a key you choose:

• Scopes: image, text or both. A key without the scope for a kind of content 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.

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 your plan's number of keys.

Keep keys on the server

• Store the key in an environment variable or your platform's secret store. The examples in these docs use OPENMOD_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 shows which key made each check, so you can see what the leaked key was used for.

Errors