API Keys - Keys

Download schema

This is an object representing an API key. This section includes a list of endpoints to perform CRUD operations on an API key. You can learn more about API keys here.

Lists keys

GET

https://dev.zuplo.com

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

Lists all keys for this consumer.

Lists 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

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.

Lists keys › 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

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

Lists keys › Responses

The request has succeeded.

Zuplo.ApiKeys.ApiKeys

Zuplo.ApiKeys.ApiKey[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Creates an API key

POST

https://dev.zuplo.com

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

Creates a new API key for this consumer. New API keys will automatically have API Key Leak Detection enabled.

Creates an API key › 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

Creates an API key › Request Body

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Creates an API key › Responses

The request has succeeded.

A Consumer can have any number of API keys associated with it. Each API Key shares the same identity (i.e. Consumer) when authenticating with this service. Keys can have their own description to note the use of the key and can have an expiration date. Expired keys will not be permitted to authenticate after their expiration.

Zuplo.ApiKeys.ApiKey

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

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

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

curl https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers/:consumerName/keys \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}'

Example Request Body

{
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}

json

Example Responses

{
  "createdOn": "2023-04-20T05:54:34.408Z",
  "updatedOn": "2023-04-20T05:54:34.408Z",
  "id": "key_m1m4ol223R0kGHGZY7tPQMQl",
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}

json

application/json

Creates multiple API keys

POST

https://dev.zuplo.com

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

Creates multiple new API keys for this consumer.

Creates multiple API 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

Creates multiple API keys › Request Body

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody[]

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Creates multiple API keys › Responses

The request has succeeded.

Zuplo.ApiKeys.ApiKeys

Zuplo.ApiKeys.ApiKey[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

POST/v1/accounts/{accountName}/key-buckets/{bucketName}/consumers/{consumerName}/keys/$bulk

curl 'https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers/:consumerName/keys/$bulk' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "0": {
    "description": "My secret api key",
    "expiresOn": "2023-04-20T05:54:34.408Z",
    "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
  },
  "1": {
    "description": "My secret api key2",
    "expiresOn": "2023-05-20T05:54:34.408Z",
    "key": "zpka_77b21c8591354c0997db232cc2f79c9e_69253f99"
  }
}'

Example Request Body

{
  "0": {
    "description": "My secret api key",
    "expiresOn": "2023-04-20T05:54:34.408Z",
    "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
  },
  "1": {
    "description": "My secret api key2",
    "expiresOn": "2023-05-20T05:54:34.408Z",
    "key": "zpka_77b21c8591354c0997db232cc2f79c9e_69253f99"
  }
}

json

Example Responses

{
  "data": [
    {
      "createdOn": "2023-04-20T05:54:34.408Z",
      "updatedOn": "2023-04-20T05:54:34.408Z",
      "id": "key_m1m4ol223R0kGHGZY7tPQMQl",
      "description": "My secret api key",
      "expiresOn": "2023-04-20T05:54:34.408Z",
      "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
    }
  ],
  "limit": 1000,
  "offset": 0
}

json

application/json

Gets an API key

GET

https://dev.zuplo.com

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

Retrieves an API key for this consumer.

Gets an API key › 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

keyId

string · required

The key id.

Gets an API key › query Parameters

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

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 an API key › Responses

The request has succeeded.

Zuplo.ApiKeys.ApiKey

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

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Updates an API key

PATCH

https://dev.zuplo.com

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

Updates an API key for this consumer.

Updates an API key › 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

keyId

string · required

The key id.

Updates an API key › 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 an API key › Request Body

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Updates an API key › Responses

The request has succeeded.

Zuplo.ApiKeys.ApiKey

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

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

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

curl https://dev.zuplo.com/v1/accounts/:accountName/key-buckets/:bucketName/consumers/:consumerName/keys/:keyId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}'

Example Request Body

{
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}

json

Example Responses

{
  "createdOn": "2023-04-20T05:54:34.408Z",
  "updatedOn": "2023-04-20T05:54:34.408Z",
  "id": "key_m1m4ol223R0kGHGZY7tPQMQl",
  "description": "My secret api key",
  "expiresOn": "2023-04-20T05:54:34.408Z",
  "key": "zpka_66b21c8591354c0997db232cc2f79c9e_69253f24"
}

json

application/json

Deletes an API key

DELETE

https://dev.zuplo.com

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

Deletes an API key for this consumer.

Deletes an API key › 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

keyId

string · required

The key id.

Deletes an API key › 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 an API key › Responses

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

No data returned

API Keys - Consumers API Keys - Managers