Service Integrations and API Keys
A Service Integration is a machine identity in Admin Portal that represents a program or service consuming the PubNub Admin API identified by an API key.
Use Service Integrations in the Admin Portal to programmatically manage your PubNub account, apps, and keysets without using the Admin Portal UI. Service Integration use cases include:
- Automation scripts that create apps and keysets as part of CI/CD pipelines
- Partner customer onboarding that automatically provisions PubNub resources for new customers
- Infrastructure as code tools like Terraform that manage PubNub configuration
- AI-powered development tools like the PubNub MCP Server that need programmatic Admin API access
Service integrations and API keys
Service Integrations authenticate using API keys. A single Service Integration can have up to three API keys. For information on creating API keys, refer to Create an API Key.
API keys can have limited permissions and expiration dates. Each Service Integration has a distinct identity for tracking and no interactive login is required for programmatic access.
API keys are only shown once at creation time. If you've lost an API key, create a new one in the same Service Integration, then revoke the old key. The new API key will have the same permissions as the old one.
Permissions model
When you create a Service Integration, you assign permissions that control what operations on which resources the Service Integration can perform. Always follow the principle of least privilege.
Permissions are immutable
You can't change the permissions of an existing Service Integration after creation. If you need different permissions, create a new Service Integration.
Permissions are granted as rows that combine:
- a Level (Account / App / Keyset)
- a PubNub resource (App / Keyset / Secret key / Usage & Monitoring / OEM Customer)
- an Access option (Read, Write, or Read & write—availability depends on the resource)
Account level permissions
Selecting Account as the level doesn't grant full access. You must add a permission row for each resource you want the Service Integration to access. Missing rows for resources result in 403 errors when calling those APIs.
Levels
Levels define the hierarchical scope at which permissions apply:
| Level | Scope | Example |
|---|---|---|
| Account | All apps and keysets in your account | Read usage metrics for the entire account. |
| App | A specific app and all its keysets | Manage keysets within a single app. |
| Keyset | A single keyset | Configure features on one keyset. |
Permissions granted at a higher level automatically apply to all resources below it. For example, granting the read permission to Usage on app level also grants it for all keysets in that app.
PubNub resources
PubNub resources define what you can operate on:
| Resource | Description | Notes |
|---|---|---|
| App | App management | Create, read, and update apps. |
| Keyset | Keyset management | Create, read, and update keysets. |
| Secret key | Secret key of a specific keyset | Manage or rotate a specific secret key. |
| Usage & Monitoring | Usage metrics | Read usage metrics for the entire account, apps, and keysets. Only supports read permissions. |
| OEM Customer | Partner Portal management | List, create, and manage Partner Customers. |
Available permissions
| Level | PubNub resource | Access | Description |
|---|---|---|---|
| Account | App | Read | List and view all apps details |
| Account | App | Read & write | Create, update, rename, and delete apps |
| Account | Keyset | Read | List and view keyset details and config |
| Account | Keyset | Read & write | Create, update, and delete keysets across whole account |
| Account | Secret key | Read | View secret keys across all keysets |
| Account | Secret key | Read & write | Rotate secret keys across all keysets |
| Account | Usage & Monitoring | Read | View usage and monitoring data for whole account |
| Account | OEM Customer | Read | List and view OEM customer data (partner accounts only) |
| Account | OEM Customer | Read & write | Create, update, and delete OEM customer data (partner accounts only) |
| App | App | Read | View details for selected app |
| App | App | Read & write | Update and delete the selected app |
| App | Keyset | Read | List and view keyset details within the selected app |
| App | Keyset | Read & write | Create, update, and delete keysets within the selected app |
| App | Secret key | Read | View secret keys for keysets within the selected app |
| App | Secret key | Read & write | Rotate secret keys for keysets within the selected app |
| App | Usage & Monitoring | Read | View usage and monitoring data for the selected app |
| Keyset | Keyset | Read | View selected keyset details and configuration |
| Keyset | Keyset | Read & write | Update and delete the selected keyset and manage it's config |
| Keyset | Secret key | Read | View secret keys for the keyset |
| Keyset | Secret key | Read & write | Rotate secret keys for the keyset |
| Keyset | Usage & Monitoring | Read | View usage and monitoring data for the keyset |
API key permission examples
Check out the following examples to see how permissions work in practice.
Full access for the entire account
The following permission rows grant full Admin API access for the entire account:
| Level | PubNub resource | Access |
|---|---|---|
| Account | App | Read & write |
| Account | Keyset | Read & write |
| Account | Secret key | Read & write |
| Account | Usage & Monitoring | Read |
| Account | OEM Customer | Read & write (for OEM customers only) |
Provision apps and keysets (no usage)
| Level | PubNub resource | Access |
|---|---|---|
| Account | App | Read & write |
| Account | Keyset | Read & write |
Read-only access
| Level | PubNub resource | Access |
|---|---|---|
| Account | App | Read |
| Account | Keyset | Read |
| Account | Usage & Monitoring | Read |
Narrowly scoped to one app
The following permission rows grant access to one app and all its keysets:
| Level | PubNub resource | Access |
|---|---|---|
| App | App ID | Read & write |
| App | Keyset ID | Read & write |
Create a Service Integration
To create a Service Integration:
-
Log in to the Admin Portal.
-
Click your account name in the top-right corner and select My Account.
-
Navigate to Organization Settings → API Management.
-
Click Create Service Integration.
-
Enter a descriptive name for the integration (for example, "CI/CD Pipeline" or "Terraform").
-
Select the permissions the integration needs. Remember to follow the principle of least privilege.
-
Choose the level for each permission (Account, App, or Keyset).
-
Choose an expiration date for the initial API key.
-
Click Create and copy the generated API key immediately, as you won't be able to view it again.
Create an API Key
Store your API key securely
Store the API key in a secure location such as a secrets manager, environment variable, or encrypted configuration file. Never commit API keys to source control.
To get the API key, you need to have or create a service integration.
-
Log in to the Admin Portal.
-
Click your account name in the top-right corner and select My Account.
-
Navigate to Organization Settings → API Management.
-
Find the Service Integration (or create a new one) to create an API key for.
-
Click + Generate API Key.
-
In the dialog that appears, choose the expiration date for the API key.
-
Click Generate API Key and copy the generated API key, as you won't be able to view it again.
API key lifecycle
API keys have built-in security controls to limit exposure.
Maximum number of API keys
You can have up to three active API keys in your account.
Expiration
- API keys have a maximum time to live of 1 year
- You can configure shorter expiration periods when creating the key
- Expired keys stop working immediately and can't be renewed
Rotation
As each Service Integration can have 3 API keys, you can rotate or revoke API keys within one Service Integration.
Revocation
To immediately revoke an API key:
-
Navigate to My Account → Organization Settings → API Management.
-
In the Service Integrations table, click the row of the Service Integration whose API key you want to revoke.
-
In the Active API Keys table, click the Revoke API key link for the API key you want to revoke. A dialog will appear asking you to confirm the revocation.
The API key stops working immediately after revocation.
API key usage
You can use API keys to authenticate with the Admin API and the PubNub MCP Server.
Best practices
Follow these best practices when working with Service Integrations:
| Practice | Description |
|---|---|
| Use descriptive names | Name integrations after their purpose (for example, "Production Deployment Pipeline") |
| Minimize permissions | Grant only the permissions each integration actually needs |
| Store keys securely | Store API keys in a secrets manager, not in source control |
| Set short expiration | Use the shortest practical expiration period for your use case |
| Rotate regularly | Replace API keys periodically, even before they expire |
| Monitor usage | Review which integrations are active and remove unused ones |
| Use separate integrations | Create distinct integrations for different environments (dev, staging, production) |