DataSync access control
DataSync is secure by default. Access Manager must be enabled on your keyset, and every request must carry a valid credential. There is no anonymous access.
DataSync extends Access Manager with new resource types for entities, relationships, and memberships. It uses the same tokens that already protect your channels. Refer to Access control and permissions management for how Access Manager tokens work in general. This page covers what DataSync adds on top.
Authorizing requests
Each DataSync request carries exactly one credential: an Access Manager token (for your clients) or a request signature (for your servers). Sending both is an error, and sending neither is rejected with a 401.
Over REST, the credential is a query parameter: auth for a token or signature for a signed request.
Your server sends signed requests to DataSync directly and grants Access Manager tokens to your client apps. Client apps then send requests to DataSync with the token. DataSync accepts both kinds of request only when the keyset has Access Manager and DataSync enabled.
Access Manager is required
If Access Manager is not enabled on your keyset, DataSync requests fail. Enable it in the Admin Portal before using DataSync.
DataSync itself is a separate keyset switch. If DataSync isn't enabled on the keyset, every request fails with a 403, whatever credential it carries. Refer to Enable DataSync.
The typical split follows the same pattern as the rest of PubNub: your servers hold signing credentials and grant tokens, and your clients use the tokens they're granted.
Permissions and resource types
Access Manager tokens grant permissions on resources. DataSync adds three resource types:
datasync:entitiesdatasync:relationshipsdatasync:memberships
User and channel entities reuse the existing users and channels resource types.
DataSync user entities use users, not uuids
DataSync checks the users resource type for user entities. It does not check uuids, the resource type App Context uses for granting access to a User ID's metadata.
A token that only grants uuids permissions does not authorize DataSync operations on the corresponding user entity. Grant users explicitly.
users and uuids are separate scopes that different products read. Keep uuids only while you still grant App Context UUID metadata permissions.
Each DataSync object kind authorizes against a specific resource type:
| Object kind | Resource type |
|---|---|
| Generic entity | datasync:entities |
| Relationship | datasync:relationships |
| Membership | datasync:memberships |
| User entity | users |
| Channel entity | channels |
Every DataSync resource type, and users, support four permissions: create, get, update, delete.
read, write, manage, and join stay messaging concepts. On channels, they gate publishing, subscribing, and Presence. A DataSync read of a channel entity uses get, not read. To receive DataSync events on an entity's channel, you need subscribe permission on that channel, granted the same way as any other channel grant.
Grants target either exact IDs or patterns (regular expressions), following the same model Access Manager uses for channels. Reading a DataSync object is get, not read.
Field-level access with projections
Beyond granting access to a resource, a token can select which fields of that resource it can read and write. Tokens carry a pn-projections map inside their meta section, with two nested maps: res for exact resource IDs and pat for regular-expression patterns.
Each is keyed by object kind plus ID (or pattern), with each value naming the projection granted for that resource. These keys use their own prefixes:
datasync:users:for usersdatasync:entities:for generic entitiesdatasync:channels:for channelsdatasync:relationships:for relationshipsdatasync:memberships:for memberships
With no matching entry in res or pat, a token gets the __default__ projection. Requesting a projection name that doesn't exist on the class is rejected with a 403.
A replace is scoped to the token's projection. Fields outside that projection keep their stored values, so a token holding a narrow projection can't wipe the fields it can't see. Refer to Projections for the full model.
Projections and events
Projections scope events as well as API reads and writes. Each event is published once per projection declared on the object's class: to the object's ID channel for __default__, and to __<projection>__<id> for each named projection, with the payload on each channel limited to that projection's fields. Grant subscribe permission on the projection channel your client needs.