---
source_url: https://www.pubnub.com/docs/data-storage/structured-data/access-control
title: DataSync access control
updated_at: 2026-09-30T07:20:08.000Z
---
# DataSync access control
## Documentation index
To discover more PubNub resources:
1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.
Do not assume a path exists, always check the index first.
DataSync is secure by default. [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) 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](https://www.pubnub.com/docs/security/access-control/overview.md) 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.
```mermaid
flowchart LR
SERVER["Your server
holds signing credentials"]
CLIENT["Client app"]
KEYSET["Keyset
Access Manager and DataSync enabled"]
DS["DataSync"]
SERVER -->|"signed request"| DS
SERVER -->|"grants token"| CLIENT
CLIENT -->|"token request"| DS
KEYSET -->|"enables both checks"| DS
class DS emphasis
class KEYSET muted
```
:::warning Access Manager is required
If Access Manager is not enabled on your keyset, DataSync requests fail. Enable it in the [Admin Portal](https://admin.pubnub.com) 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](https://www.pubnub.com/docs/data-storage/structured-data/enable-structured-data.md).
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:entities`
* `datasync:relationships`
* `datasync:memberships`
User and channel entities reuse the existing `users` and `channels` resource types.
:::warning 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](https://www.pubnub.com/docs/data-storage/metadata/overview.md) 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](https://www.pubnub.com/docs/presence/overview.md). 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 users
* `datasync:entities:` for generic entities
* `datasync:channels:` for channels
* `datasync:relationships:` for relationships
* `datasync: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](https://www.pubnub.com/docs/data-storage/structured-data/projections.md) for the full model.
:::note 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 `____` 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.
:::
Last updated at: 2026-09-30T07:20:08.000Z