Consumers

Links a consumer in the bucket to the app, so the consumer's keys call the app. Create the consumer first with POST …/consumers, with include[]=apiKey for its first key. The app then lists it in its consumers. Returns 201 when the consumer was linked and 200 when it already was, so sending the same request again changes nothing. Unlink it with DELETE …/ai/apps/{appId}/consumers/{consumerId}.

A consumer is linked to at most one app. Fails with 409 when another app holds it, when it is a person's consumer in a user app, or when it has managers (an app's consumers have none: remove them first), and with 404 when the app is not in the bucket. A consumerId that is not in the bucket is a 400. Only people who manage the bucket's consumers can link one; pool admins get 403.

Returns the link between the app and one of its consumers. Read the consumer itself at …/consumers/{consumerId}. Fails with 404 when the consumer is not linked to the app. People who manage the bucket's consumers and the members of the app's pool can read it.

Unlinks the consumer from the app. The consumer stays in the bucket with its keys, which no longer call the app, so it can be linked again. Delete it at …/consumers/{consumerId} to revoke its keys. A repeated unlink returns 404, which clients should treat as success. Only people who manage the bucket's consumers can unlink one; pool admins get 403.

Lists one person's consumers in the user app, oldest first, for example one per laptop. People list their own with their own userId. User app admins can list anyone's.

Creates a consumer for one person in the user app, for example for Claude Code on their laptop. People create their own with their own userId. A user app admin can create one for anyone who can use the user app, one request per person. Fails with 404 when the person cannot use the user app.

With include[]=apiKey it also issues the consumer's first key, and the response contains the key's secret. The person can read it again at …/api-keys/{apiKeyId}/secret, so a key an admin issued reaches them without the admin handing it over.

Lists the consumers the bucket holds, oldest first: those of API key authentication on any gateway, such as customers and partners, and those linked to AI apps. Filter by name to find one consumer, or by managerEmail to list the consumers a person manages. People's consumers are listed under them. Only people who manage the bucket's consumers can list them; others get 403.

Creates a consumer in the bucket. Its name is unique in the bucket and cannot be changed later. With include[]=apiKey it also issues the consumer's first key. The response then contains the key's secret, the only time it is returned. Link it to an AI app with POST …/ai/apps/{appId}/consumers. Fails with 409 when the bucket already has a consumer with this name, including people's consumers, which are not listed here. Only people who manage the bucket's consumers can create one; others, pool admins included, get 403.

managers lists the people who manage the consumer's keys in your developer portal, by email. They see its keys there once they sign in with that address. A consumer you will link to an app has no managers, because linking a consumer that has managers fails with 409.

Returns a consumer, whether an app, a person or the bucket holds it. List its keys at …/consumers/{consumerId}/api-keys. People who manage the bucket's consumers read any consumer that is not a person's. The person and the user app's admins read a person's consumer, and the members of a pool read the consumers linked to the pool's apps.

Updates a consumer with JSON Merge Patch semantics: omitted properties are unchanged and null clears a property. tags are merged key by key and metadata as a JSON Merge Patch, and a key set to null is removed. managers replaces all of the consumer's managers, so send the complete list; [] removes them all. A consumer's name and what holds it cannot be changed.

Only a consumer the bucket holds has managers: managers on a consumer linked to an app, or on a person's consumer, is a 400.

The person and the user app's admins change a person's consumer. Any other consumer is changed only by people who manage the bucket's consumers, not by pool admins. Others get 403.

Deletes a consumer, with its managers, and revokes all of its API keys. A repeated delete returns 404, which clients should treat as success. Who can delete it is who can change it (PATCH); others get 403. A consumer that holds a subscription (API monetization) cannot be deleted and gets 409.