Keyset credentials and authorization
PubNub identifies connections using two things: your keyset's publish and subscribe keys (which application is connecting) and a User ID (which client within that application). Neither of these is authorization. They are identification only.
Authorization is handled exclusively by Access Manager. Without it enabled on your keyset, any client holding your publish and subscribe keys has unrestricted access to every channel and every stored record on that keyset.
PubNub doesn't log users in or verify passwords, so your own application authenticates the user and then hands PubNub the resulting identity. This page explains how those three layers relate to each other and introduces the Admin Portal, the console where all three are created and configured.
Your app sets the publish and subscribe keys and the User ID when it initializes the SDK. Your server holds the secret key and uses it to grant an Access Manager token. Your app then sets that token with setToken(). PubNub checks the keys on every request. It checks the token only if Access Manager is enabled on the keyset, and it trusts the User ID as your app provides it.
| Layer | Answers the question | Set by | Checked by |
|---|---|---|---|
| Publish and subscribe keys | Which application is this? | Your app, at SDK initialization | PubNub, on every request |
| User ID | Which client within that application? | Your app, after its own login | Trusted as provided by your app |
| Access Manager token | What is this client allowed to do? | Your server, using the secret key | PubNub, only if Access Manager is enabled on the keyset |
Your users' logins
Signing users in (checking a password, running an OAuth flow, validating an SSO assertion) is entirely your application's responsibility. PubNub has no concept of a username or a login screen. By the time your client initializes a PubNub SDK, that login has already happened elsewhere, and your app tells PubNub which identity to attach to this connection.
This means PubNub's three layers answer different questions than a typical login system does:
- Publish and subscribe keys identify which application is reaching the PubNub network
- A User ID labels which client, within that application, is doing what
- A token limits what the client with that User ID can reach
Your own login system is what checks that the user of your app is who they claim to be. If you skip building that layer, any client that has your keys can connect as any User ID it chooses.
Application credentials
Every keyset issued from the Admin Portal has three PubNub-generated keys:
- a publish key, for your app
- a subscribe key, for your app
- a secret key, for your server
Your app passes the publish and subscribe keys to the SDK at initialization. PubNub uses them to identify which keyset a connection belongs to, and therefore which app, which features, and which bill.
Publish and subscribe keys are bearer credentials: whoever holds them can act as your application. Without Access Manager enabled, that means unrestricted read and write access to every channel and every piece of stored metadata on the keyset. Public exposure of these keys, for example in a compiled mobile app or a public JavaScript bundle, is therefore an expected condition rather than a security failure. Access Manager, not key secrecy, is what actually restricts access.
A keyset also has a secret key, generated alongside the publish and subscribe keys.
The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications.
The secret key is what your server uses to grant Access Manager tokens. It is a different kind of credential from the publish and subscribe keys, closer to a root credential for the keyset than to an application identifier.
Client identity
Once PubNub knows which application is connecting, it needs to know which client within that application it's talking to. That's the job of the User ID.
User ID / UUID
User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.
PubNub trusts the User ID your app supplies. It doesn't independently verify that the value corresponds to a real, currently-logged-in person.
Your own login system is what makes that trust reasonable. Typically, your server assigns a User ID during account creation, stores it with the user's profile, and hands it to the client only after a successful login. The client then reuses that same User ID for the lifetime of the account, across sessions and devices. For the full identification model, including billing and Presence implications, see User ID.
What Access Manager restricts
A User ID tells PubNub who is connected. It doesn't, by itself, limit what that connection can reach. Access Manager, once enabled on the keyset, is what adds that restriction.
Access Manager isn't enabled by default
With Access Manager enabled, your server uses the secret key to grant a signed, time-limited token scoped to permissions on specific channels, channel groups, or user metadata. The token can also be bound to one authorized User ID. PubNub then rejects any request that presents the token from a different User ID than the one it was issued for.
For more information, refer to Security overview.
Protecting your keys
Keysets are usually split by environment (development, QA, and production) so that a key compromised or misconfigured in one environment can't reach another. Each keyset holds the publish, subscribe, and secret keys described above. Its overview page is where you enable Access Manager and other PubNub features, and where paid plans can rotate the secret key without downtime.
Because every credential and every permission decision lives on a keyset, controlling who can reach the Admin Portal is itself part of your access control story. Organization owners can invite additional members and assign roles that control who may view keys, rotate secrets, or change keyset configuration. Every credential-affecting change is recorded in the Audit Log.