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 $OPENSHIELD_API_KEY" ...

# The X-Api-Key header
curl -H "X-Api-Key: $OPENSHIELD_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, and for 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

• 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 shows which key made each check, so you can see what the leaked key was used for.

Errors