Organization Service Keys

Organization service keys let an integration obtain API tokens without a person generating a new token each time. Keys belong to a Wildbook organization and use its dedicated service account. They do not use the personal access rights of the administrator who created them.

This feature is available in Wildbook 11.0. For a one-time analysis or interactive task, start with a personal API token.

Who Can Manage Keys?

• Site administrators can manage keys for any organization.

• Users with the orgAdmin role can manage keys for organizations they belong to directly.

• The orgSuper role alone does not grant key-management access. Membership in a parent organization alone does not grant access to a child organization’s keys.

Managing keys requires confirming your Wildbook password. A browser session, personal API token, or service key alone cannot manage keys.

Create a Service Key

1. Sign in and select API Access from your account menu.

2. Select Manage service keys, enter your password, and select Confirm.

3. In Organization service keys, select the intended Organization.

4. Under Create service key, enter a Label that identifies the integration, such as Monthly catalog analysis.

5. Select the required Scopes from the table below.

6. Set Valid for (days, 1-365). The default is 90 days.

7. Select Create service key and confirm your password.

8. Copy the key into your integration’s secret store before selecting Done or closing the panel. The complete key is shown only once.

Each organization can have at most two active keys. An active key has not expired or been revoked. Use the second slot to replace a key without interrupting the integration.

Scope	Allows the integration to request
data:read	Tokens for the general read API, limited to data the service account can access
submissions:read	Tokens to read that service account’s submission status and results
submissions:write	Tokens to create, upload, validate, and commit submissions, and read their status and results

Select only the scopes the integration needs. A key can allow more than one scope, but each token is issued for one purpose. A key with submissions:write can also request a submissions:read token. Neither submission scope grants access to the general read API.

Creating the first key provisions the organization’s service account. That account cannot sign in through the normal password login flow. Access checks use the service account’s permissions, not the key creator’s permissions.

For submission writes, a site administrator must separately grant api-submission to the organization’s service account, and the submissions pilot must be enabled. Selecting submissions:write when creating a key does not enroll the account or enable the pilot. See Data Import Access.

Exchange a Key for a Token

A service key begins with wbsvc_. Send it only to the token endpoint on the Wildbook that issued it. The following HTTP example uses a placeholder, not a real credential:

POST /api/v3/auth/token?scope=data:read HTTP/1.1
Authorization: Bearer wbsvc_<key-id>.<secret>

Omitting scope requests the same general read access as scope=data:read. Use scope=submissions:read or scope=submissions:write for the submission workflow.

A successful response includes:

• token: the short-lived bearer token to use for API requests.

• tokenType: Bearer.

• expiresInSeconds: how long that token remains valid.

• keyExpiresAt: the service key’s expiration as milliseconds since the Unix epoch.

Send the returned token, rather than the service key, to the API routes documented by your Wildbook:

Authorization: Bearer <returned-token>

Reuse the token until it is close to expiry, then exchange the service key again. Do not exchange the key before every API request. Service-key tokens last at most 15 minutes, may be shorter depending on server configuration, and cannot outlive the key. Use the response’s expiresInSeconds to schedule renewal.

Store the service key in the integration’s secret store. Keep it out of chat, source files, URLs, and logs. For request examples and data access details, fetch /api/v3/agent-skill/api-reference from your Wildbook; for submissions, fetch /api/v3/agent-skill/submit-sightings.

Review, Replace, or Revoke Keys

The key list shows each key’s label, scopes, expiration, creator, last use, and status. Last used records a successful exchange for a token; it is not a record of every API request. Never means no successful exchange has been recorded.

To replace a key before it expires:

1. Create a replacement with the scopes the integration needs.

2. Update the integration’s secret store.

3. Confirm that it can exchange the replacement and perform its intended API requests.

4. Select Revoke for the old key, confirm the action, and enter your password.

If both active-key slots are occupied, identify which key can be retired before creating another. If you lose a key’s secret, revoke it and create a replacement; the existing secret cannot be displayed again.

To stop one integration’s key from issuing tokens, select Revoke beside it. Revoke all revokes every key for the selected organization and can interrupt every integration using those keys.

Revocation prevents further token exchanges immediately. Tokens already issued can continue working until they expire, for at most 15 minutes. Revocation is permanent; create a new key if access is needed again.

Troubleshooting

Problem	What to check
Manage service keys is missing	Confirm that your account has the admin or orgAdmin role and that your Wildbook supports this feature.
No organizations are available for service keys	An organization administrator must be a direct member of the organization. Ask a site administrator to check membership and roles.
The organization already has two active keys	Revoke a key that is no longer needed before creating another.
The service account needs attention	Ask a site administrator to restore its eligibility. It must belong directly to its own organization only and must not have admin, orgAdmin, or orgSuper roles.
Token exchange returns 401	Check whether the key is invalid, expired, revoked, or unavailable. A revoked or expired key must be replaced.
Token exchange returns 403	Check that the key allows the requested scope. Submission writes also require service-account enrollment and enabled submission admission.
Token exchange returns 503	Ask the operator to check token issuance and service-account configuration.
The token cannot see expected data	Check the service account’s data access. The key does not inherit the administrator’s personal access.

For site operators, service keys and submission enrollment use context0 in Wildbook 11.0. Keep the service account attached to its owning organization; changing its membership or granting administrative roles can make its keys unusable.