Create a new keyset

Creates a new keyset in a specified app either with default configuration or with optional configuration provided with request. For more configuration examples, see the config section of the API. In the response you will receive the keyset and the configuration with defaults set, if were not provided upon creation.

Note:

  • Creating a keyset requires both keyset:write and keyset-secret:read permissions on the app. The secretKeys field will always be included in the creation response.
  • Secret keys are only available at creation time and will not be returned in subsequent GET requests.
  • file.region and appContext.region cannot be changed after initial setup.
Header Parameters
PubNub-Version string — REQUIRED

Possible values: [2025-11-15]

Request Body — REQUIRED
keyset object — REQUIRED
name string

A human-readable name for the keyset.

type string

Possible values: [testing, production]

The type of the keyset, either "testing" or "production". Testing keysets are used for development and testing purposes and can be affected with stronger rate limits. Upgrading from testing to production keyset requires a paid plan.

appId string — REQUIRED

The ID of the app this this keyset belongs to.

config object
accessManager object
enabled boolean

Enable or disable Access Manager

tokenRevoke

Enables token invalidation so it can't access to PubNub resources. Enabling this may introduce some latency in your API calls to check the validity of the token

files object
enabled boolean

Enable or disable file sharing

retention

Number of days to retain files. Valid values: 1, 7, 30, 90, 180, 365, or 0 for unlimited. Align file retention with your Message Persistence settings to keep messages and files for the same duration.

region

The geographical region where PubNub stores and manages your files. Once a region is set it cannot be changed. Valid values: us-east-1, us-west-1, eu-central-1, ap-south-1, ap-northeast-1. Align file retention with your Message Persistence settings to keep messages and files for the same duration.

streamController object
enabled boolean

Enable or disable stream controller

wildcardSubscribe boolean

Allows subscribing to wildcard channels (eg. foo.*)

channelGroupLimit
appContext object
enabled boolean

Enable or disable app context

region

The geographic region where your App Context data is stored and managed. Choose a region close to your users to reduce latency and improve performance. Once a region is set it cannot be changed. Valid values: aws-iad-1, aws-pdx-1, aws-fra-1, aws-bom-1, aws-hnd-1.

userMetadataEvents boolean

Enable or disable user metadata events, which are triggered when user metadata is set or removed in the objects database.

channelMetadataEvents boolean

Enable or disable channel metadata events, which are triggered when channel metadata is set or removed in the objects database. Apps can subscribe and update UI based on channel property changes.

membershipEvents boolean

Enables or disables membership (associations between users and channels) events, which are triggered when memberships are added, updated or removed in the objects database. This helps you manage and respond to who belongs to which channels. Subscribe to receive and handle these events.

disallowGetAllChannelMetadata boolean

If enabled, the “Get All Channel Metadata” call is disallowed. If you enable Access Manager and leave this unchecked, you can get all channel metadata without listing it in the token’s permission schema.

disallowGetAllUserMetadata boolean

If enabled, the “Get All User Metadata” call is disallowed. If you enable Access Manager and leave this unchecked, you can get all user metadata without listing it in the token’s permission schema.

referentialIntegrity boolean

When enabled: you can create a membership only if the specified user ID and channel ID exist as standalone metadata entities. Deleting a user or channel automatically deletes its child membership associations. When disabled: you can create memberships even if the user or channel entity doesn’t exist. Deleting a user or channel doesn’t delete associated memberships.

apns object
enabled boolean
teamId
authKeyId
filename
tokenContent string

Token file content as string (private key)

fcm object
filename
keyFile object

FCM API Key file, downloaded from the Firebase Console, JSON format

messagePersistence object
enabled boolean

Enable or disable message persistence

retention

Number of days to retain messages. Valid values: 1, 7, 30, 90, 180, 365, or 0 for unlimited. Align message retention with your File Sharing settings to keep messages and files for the same duration.

includePresenceEvents boolean

Store presence event messages in message history.

deleteFromHistory boolean

A setting that lets you use API calls to delete specific messages previously stored in a channel's message history.

presence object
enabled boolean

Enable or disable presence

announceMax
interval
deltas
generateLeaveOnDisconnect
streamFiltering

Once enabled, filters presence events at the client. You receive only relevant events on the Presence channel (for example, join events for a specific User ID).

activeNoticeChannel

Sends notifications when a channel switches between active (has subscribers) and inactive (no subscribers).

debounce
Responses
201

Success

Schema — OPTIONAL
keyset object
name string — OPTIONAL

A human-readable name for the keyset.

type string — OPTIONAL

Possible values: [testing, production]

The type of the keyset, either "testing" or "production". Testing keysets are used for development and testing purposes and can be affected with stronger rate limits. Upgrading from testing to production keyset requires a paid plan.

appId string

The ID of the app this this keyset belongs to.

id string
publishKey string
subscribeKey string
createdAt string — OPTIONAL
updatedAt string — OPTIONAL
secretKeys object[]

Array of secret keys for the keyset. Should contain exactly one non-expiring keyset.

secretKey string
expiresAt

Expiration timestamp in ISO 8601 UTC format (e.g., "2025-12-31T23:59:59Z"). null means the secret key will not expire.

config object — OPTIONAL
accessManager object
enabled boolean

Enable or disable Access Manager

tokenRevoke

Enables token invalidation so it can't access to PubNub resources. Enabling this may introduce some latency in your API calls to check the validity of the token

files object
enabled boolean

Enable or disable file sharing

retention

Number of days to retain files. Valid values: 1, 7, 30, 90, 180, 365, or 0 for unlimited. Align file retention with your Message Persistence settings to keep messages and files for the same duration.

region

The geographical region where PubNub stores and manages your files. Once a region is set it cannot be changed. Valid values: us-east-1, us-west-1, eu-central-1, ap-south-1, ap-northeast-1. Align file retention with your Message Persistence settings to keep messages and files for the same duration.

streamController object
enabled boolean

Enable or disable stream controller

wildcardSubscribe boolean

Allows subscribing to wildcard channels (eg. foo.*)

channelGroupLimit

Channel group limit between 1 and 2000 for paid plans only, free plans have a limit of 100

appContext object
enabled boolean

Enable or disable app context

userMetadataEvents boolean

Enable or disable user metadata events, which are triggered when user metadata is set or removed in the objects database.

channelMetadataEvents boolean

Enable or disable channel metadata events, which are triggered when channel metadata is set or removed in the objects database. Apps can subscribe and update UI based on channel property changes.

membershipEvents boolean

Enables or disables membership (associations between users and channels) events, which are triggered when memberships are added, updated or removed in the objects database. This helps you manage and respond to who belongs to which channels. Subscribe to receive and handle these events.

disallowGetAllChannelMetadata boolean

If enabled, the “Get All Channel Metadata” call is disallowed. If you enable Access Manager and leave this unchecked, you can get all channel metadata without listing it in the token’s permission schema.

disallowGetAllUserMetadata boolean

If enabled, the “Get All User Metadata” call is disallowed. If you enable Access Manager and leave this unchecked, you can get all user metadata without listing it in the token’s permission schema.

referentialIntegrity boolean

When enabled: you can create a membership only if the specified user ID and channel ID exist as standalone metadata entities. Deleting a user or channel automatically deletes its child membership associations. When disabled: you can create memberships even if the user or channel entity doesn’t exist. Deleting a user or channel doesn’t delete associated memberships.

region

The geographic region where your App Context data is stored and managed. Choose a region close to your users to reduce latency and improve performance. Once a region is set it cannot be changed. Valid values: aws-iad-1, aws-pdx-1, aws-fra-1, aws-bom-1, aws-hnd-1.

apns object

Connection details for APNs when you use it as a push service provider to deliver push notifications to your application. https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns. On the setup, you need to provide the file, you won't be able to retrieve it later from our API. If you need to identify the uploaded configuration, you can use the filename.

enabled boolean
teamId
authKeyId
filename
fcm object

Connection details for FCM when you use it as a push service provider to deliver push notifications to your application. https://firebase.google.com/docs/cloud-messaging. On the setup, you need to provide the file, you won't be able to retrieve it later from our API. If you need to identify the uploaded configuration, you can use the filename.

filename
messagePersistence object
enabled boolean

Enable or disable message persistence

includePresenceEvents boolean

Store presence event messages in message history.

deleteFromHistory boolean

A setting that lets you use API calls to delete specific messages previously stored in a channel's message history.

retention

Number of days to retain messages. Valid values: 1, 7, 30, 90, 180, 365, or 0 for unlimited. Align message retention with your File Sharing settings to keep messages and files for the same duration.

presence object
enabled boolean

Enable or disable presence

deltas
generateLeaveOnDisconnect
streamFiltering

Once enabled, filters presence events at the client. You receive only relevant events on the Presence channel (for example, join events for a specific User ID).

activeNoticeChannel

Sends notifications when a channel switches between active (has subscribers) and inactive (no subscribers).

announceMax

Maximum number of occupants in a channel before announcements switch to emitting occupancy counts instead of emitting "join", "leave" and "timeout" events. Valid range: 0-100.

interval

Cadence in seconds between each announcement of the channel occupancy. Valid range: 10-3600 seconds.

debounce

The number of seconds to wait before allowing implicit "joins" after an explicit "leave". Valid range: 0-60 seconds. Helps smooth out rapid state changes.

400

Bad Request Error

Schema — OPTIONAL
statusCode number
error string

Possible values: [BadRequest]

message string[]
401

UnauthorizedError

Schema — OPTIONAL
statusCode number
error string

Possible values: [Unauthorized]

message string[]
403

ForbiddenError

Schema — OPTIONAL
undefined
404

NotFoundError

Schema — OPTIONAL
statusCode number
error string

Possible values: [NotFound]

message string[]
500

InternalErrorError

Schema — OPTIONAL
statusCode number
error string

Possible values: [InternalError]

message string[]
* required
PubNub-Version*
Type: string
Possible values: [2025-11-15]
* required
keyset*
Type: object
config
Type: object
Example Request
{
  "keyset": {
    "name": "My Production Keyset",
    "type": "production",
    "appId": "app_123456"
  },
  "config": {
    "accessManager": {
      "enabled": true,
      "tokenRevoke": true
    }
  }
}
keyset
Type: object
config
Type: object
Example Response
{
  "keyset": {
    "name": "My Production Keyset",
    "type": "production",
    "appId": "app_123456",
    "id": "keyset_abc123",
    "publishKey": "pub-c-1234567890abcdef",
    "subscribeKey": "sub-c-1234567890abcdef",
    "createdAt": "2025-10-27T12:00:00Z",
    "updatedAt": "2025-10-27T12:00:00Z",
    "secretKeys": [
      {
        "secretKey": "sec-c-1234567890abcdef",
        "expiresAt": null
      }
    ]
  },
  "config": {
    "accessManager": {
      "enabled": true,
      "tokenRevoke": true
    },
    "files": {
      "enabled": true,
      "retention": 90,
      "region": "us-east-1"
    },
    "streamController": {
      "enabled": true,
      "wildcardSubscribe": true,
      "channelGroupLimit": 50
    },
    "appContext": {
      "enabled": true,
      "userMetadataEvents": true,
      "channelMetadataEvents": true,
      "membershipEvents": true,
      "disallowGetAllChannelMetadata": false,
      "disallowGetAllUserMetadata": false,
      "referentialIntegrity": true,
      "region": "aws-iad-1"
    },
    "apns": {
      "enabled": true,
      "teamId": "ABCD1234EF",
      "authKeyId": "XYZ9876ABC",
      "filename": "AuthKey_XYZ9876ABC.p8"
    },
    "fcm": {
      "filename": "firebase-service-account.json"
    },
    "messagePersistence": {
      "enabled": true,
      "includePresenceEvents": false,
      "deleteFromHistory": true,
      "retention": 30
    },
    "presence": {
      "enabled": true,
      "deltas": true,
      "generateLeaveOnDisconnect": true,
      "streamFiltering": true,
      "activeNoticeChannel": null,
      "announceMax": 20,
      "interval": 30,
      "debounce": 5
    }
  }
}
statusCode
Type: number
error
Type: string
Enum (1 values)
View all values
"BadRequest"
message
Type: array
Array items:
items
Type: string
statusCode
Type: number
error
Type: string
Enum (1 values)
View all values
"Unauthorized"
message
Type: array
Array items:
items
Type: string
statusCode
Type: number
error
Type: string
Enum (1 values)
View all values
"NotFound"
message
Type: array
Array items:
items
Type: string
statusCode
Type: number
error
Type: string
Enum (1 values)
View all values
"InternalError"
message
Type: array
Array items:
items
Type: string