API Keys - Consumers

Download schema

A Consumer is an object representing a group of API keys in a given bucket. This section includes a group of endpoints available to perform CRUD operations on a consumer. You can learn more about consumers here.

Lists consumers

GET

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers

Lists all consumers belonging to this account.

Lists consumers › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

Lists consumers › query Parameters

limit

integer · min: 1 · max: 1000 · required

The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used. Default: 1000

offset

integer · min: 0 · required

The offset of the first item returned in the collection. Default: 0

include-api-keys

boolean

Include the api key data in the response.

include-manager-invites

boolean

Include the manager invites data in the response.

include-managers

boolean

Include the manager's data in the response.

key-format

Zuplo.ApiKeys.KeyFormat · enum

The format of the key to return. none: Key is completely hidden. visible: Key is completely visible. masked: Part of key suffix is visible.

Enum values:

none

visible

masked

manager-email

string

Filter by email address of key manager.

tag

string

Query by tag. Example usage is tag.account=foo, where account is the name of the tag property and foo is the value.

Lists consumers › Responses

The request has succeeded.

Zuplo.ApiKeys.Consumers

Zuplo.ApiKeys.Consumer[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

GET/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers

curl 'https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers?limit=<number>&offset=<number>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
      "name": "zup-inc",
      "createdOn": "2023-04-20T05:54:34.408Z",
      "updatedOn": "2023-04-20T05:54:34.408Z",
      "description": "Consumer for zup inc",
      "tags": {
        "foo": "bar"
      },
      "metadata": {
        "id": "zup-id-343"
      },
      "managers": [
        {
          "id": "eusr_MeefoYod5eQN33MEjC4PeRFH",
          "createdOn": "2023-06-19T17:32:11.990Z",
          "email": "mgr@zuploinc.com",
          "sub": "sub-oauth2|113533232396018044159"
        }
      ],
      "apiKeys": [
        {
          "id": "key_AM7eAiR0BiaXTam951XmC9kK",
          "description": "api key for zup inc",
          "createdOn": "2023-06-19T17:32:17.737Z",
          "updatedOn": "2023-06-19T17:32:17.737Z",
          "expiresOn": "2035-06-19T17:32:17.737Z",
          "key": "****69ff2f90"
        }
      ]
    }
  ],
  "offset": 0,
  "limit": 1000
}

json

application/json

Creates a consumer

POST

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers

Creates a new consumer for this account.

Creates a consumer › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

Creates a consumer › query Parameters

with-api-key

boolean

If an API key should be created with the consumer.

Creates a consumer › Request Body

Zuplo.ApiKeys.ConsumerCreateBody

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Email addresses of the managers to invite or a list of managers (with subs) to add to the consumer.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

Creates a consumer › Responses

The request has succeeded.

Consumers are the core of the API Key service. The consumer is the 'identity' of any API Keys that are created.

Zuplo.ApiKeys.Consumer

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

POST/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers

curl https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "zup-inc",
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  },
  "managers": [
    {
      "id": "123",
      "email": "user@example.com",
      "sub": "oauth2|113533232396018044159",
      "createdOn": "2023-06-19T17:32:11.990Z"
    }
  ]
}'

Example Request Body

{
  "name": "zup-inc",
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  },
  "managers": [
    {
      "id": "123",
      "email": "user@example.com",
      "sub": "oauth2|113533232396018044159",
      "createdOn": "2023-06-19T17:32:11.990Z"
    }
  ]
}

json

Example Responses

{
  "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
  "name": "zup-inc",
  "createdOn": "2023-04-20T05:54:34.408Z",
  "updatedOn": "2023-04-20T05:54:34.408Z",
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  },
  "managers": [
    {
      "id": "eusr_MeefoYod5eQN33MEjC4PeRFH",
      "createdOn": "2023-06-19T17:32:11.990Z",
      "email": "mgr@zuploinc.com",
      "sub": "sub-oauth2|113533232396018044159"
    }
  ],
  "apiKeys": [
    {
      "id": "key_AM7eAiR0BiaXTam951XmC9kK",
      "description": "api key for zup inc",
      "createdOn": "2023-06-19T17:32:17.737Z",
      "updatedOn": "2023-06-19T17:32:17.737Z",
      "expiresOn": "2035-06-19T17:32:17.737Z",
      "key": "****69ff2f90"
    }
  ]
}

json

application/json

Gets a consumer

GET

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}

Gets a consumer given a bucket name and the consumer's name or ID.

Gets a consumer › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

consumerName

string · required

The name or ID of the consumer. Prefer the consumer's immutable id (for example csmr_brw0leTAVw478VFKD4F6OqVI); the name (for example zup-inc) remains accepted for compatibility. Within the bucket, a consumer whose name matches the value wins; otherwise the value is treated as a consumer ID. Consumer IDs are case-sensitive.

Gets a consumer › query Parameters

include-api-keys

boolean

Include the api key data in the response.

key-format

Zuplo.ApiKeys.KeyFormat · enum

The format of the key to return. none: Key is completely hidden. visible: Key is completely visible. masked: Part of key suffix is visible.

Enum values:

none

visible

masked

include-managers

boolean

Include the manager's data in the response.

include-manager-invites

boolean

Include the manager invites data in the response.

tag

string

Query by tag. Example usage is tag.account=foo, where account is the name of the tag property and foo is the value.

Gets a consumer › Responses

The request has succeeded.

Consumers are the core of the API Key service. The consumer is the 'identity' of any API Keys that are created.

Zuplo.ApiKeys.Consumer

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

GET/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}

curl https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers/:consumerName \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
  "name": "zup-inc",
  "createdOn": "2023-04-20T05:54:34.408Z",
  "updatedOn": "2023-04-20T05:54:34.408Z",
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  },
  "managers": [
    {
      "id": "eusr_MeefoYod5eQN33MEjC4PeRFH",
      "createdOn": "2023-06-19T17:32:11.990Z",
      "email": "mgr@zuploinc.com",
      "sub": "sub-oauth2|113533232396018044159"
    }
  ],
  "apiKeys": [
    {
      "id": "key_AM7eAiR0BiaXTam951XmC9kK",
      "description": "api key for zup inc",
      "createdOn": "2023-06-19T17:32:17.737Z",
      "updatedOn": "2023-06-19T17:32:17.737Z",
      "expiresOn": "2035-06-19T17:32:17.737Z",
      "key": "****69ff2f90"
    }
  ]
}

json

application/json

Updates a consumer

PATCH

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}

Update the consumer with the matching consumer name or ID.

Updates a consumer › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

consumerName

string · required

Updates a consumer › query Parameters

tag

string

Query by tag. Example usage is tag.account=foo, where account is the name of the tag property and foo is the value.

Updates a consumer › Request Body

Zuplo.ApiKeys.ConsumerUpdateBody

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

Updates a consumer › Responses

The request has succeeded.

Consumers are the core of the API Key service. The consumer is the 'identity' of any API Keys that are created.

Zuplo.ApiKeys.Consumer

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

PATCH/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}

curl https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers/:consumerName \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  }
}'

Example Request Body

{
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  }
}

json

Example Responses

{
  "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
  "name": "zup-inc",
  "createdOn": "2023-04-20T05:54:34.408Z",
  "updatedOn": "2023-04-20T05:54:34.408Z",
  "description": "Consumer for zup inc",
  "tags": {
    "foo": "bar"
  },
  "metadata": {
    "id": "zup-id-343"
  },
  "managers": [
    {
      "id": "eusr_MeefoYod5eQN33MEjC4PeRFH",
      "createdOn": "2023-06-19T17:32:11.990Z",
      "email": "mgr@zuploinc.com",
      "sub": "sub-oauth2|113533232396018044159"
    }
  ],
  "apiKeys": [
    {
      "id": "key_AM7eAiR0BiaXTam951XmC9kK",
      "description": "api key for zup inc",
      "createdOn": "2023-06-19T17:32:17.737Z",
      "updatedOn": "2023-06-19T17:32:17.737Z",
      "expiresOn": "2035-06-19T17:32:17.737Z",
      "key": "****69ff2f90"
    }
  ]
}

json

application/json

Deletes a consumer

DELETE

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}

Deletes the consumer with the matching name or ID, and any related resources.

Deletes a consumer › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

consumerName

string · required

Deletes a consumer › query Parameters

tag

string

Query by tag. Example usage is tag.account=foo, where account is the name of the tag property and foo is the value.

Deletes a consumer › Responses

There is no content to send for this request, but the headers may be useful.

No data returned

Roll consumer keys

POST

https://dev.zuplo.com

/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}/roll-key

Sets an expiration date on keys that have none and creates a new key for the consumer with the matching name or ID.

Roll consumer keys › path Parameters

accountName

string · required

The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.

bucketName

string · required

The name of the bucket. Zuplo automatically creates a bucket for your project. You can find it in youe Zuplo Portal under Settings > Project Information.

consumerName

string · required

Roll consumer keys › query Parameters

tag

string

Query by tag. Example usage is tag.account=foo, where account is the name of the tag property and foo is the value.

Roll consumer keys › Request Body

Zuplo.Common.ExpiresOnField

expiresOn

string · date-time · required

When the item will expire.

Example: 2050-04-18T05:54:34.408Z

Roll consumer keys › Responses

There is no content to send for this request, but the headers may be useful.

No data returned

API Keys - Buckets API Keys - Keys