> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Principals

> Users, groups, and roles: where each comes from, and how a GRANT or REVOKE statement names one.

**Applies to:** Embedded ❌, Enterprise ✅

A grant names one of three kinds of subject:

| Subject | Where it comes from |
| - | - |
| User (principal) | Your identity provider -- OIDC, Microsoft Entra, Okta, or Keycloak. LanceDB never creates one. |
| Group | Also your identity provider. LanceDB never creates one. |
| Role | LanceDB itself. There is no statement that creates a role -- naming one in a grant is what brings it into existence. |

## Naming a subject in SQL

`GRANT` and `REVOKE` accept a role, user, or group name directly, with an
optional keyword to disambiguate:

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT USAGE ON SECRET platform.`openai-prod` TO ROLE research
GRANT USAGE ON SECRET platform.`openai-prod` TO USER alice
GRANT USAGE ON SECRET platform.`openai-prod` TO GROUP `data-science`
```

A `USER` or `GROUP` name is resolved against your identity provider, but
only after the caller's `OWNERSHIP` on the object is checked. A name that
isn't found, or that matches more than one identity, is an error -- not a
silent no-op. `ROLE` needs no such lookup, since a role is simply whatever
name a grant has used.

Name several subjects of the same kind in one statement by omitting the
keyword after the first:

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT USAGE ON SECRET platform.`openai-prod` TO ROLE etl, rotation_service
```

## Role membership in SQL

SQL manages which users or groups a role applies to -- its membership --
directly:

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT ROLE analysts TO USER alice
GRANT ROLE analysts TO GROUP `data-science`
REVOKE ROLE analysts FROM USER alice
SHOW ROLE BINDINGS
```

Changing membership (`GRANT`/`REVOKE ROLE`) needs system `OPERATE`;
`SHOW ROLE BINDINGS` needs only system `USAGE`. A role binding accepts a
`USER` or `GROUP` on the receiving side, never another `ROLE` -- granting
a privilege to a role before anyone is a member of it is still valid; the
role simply has no effect until it has members.

## What to read next

> [card] [Authorization](https://docs.lancedb.com/governance/authorization.md)
>
> The access-control model a grant is built from.

> [card] [Privileges](https://docs.lancedb.com/governance/privileges.md)
>
> Every object's privileges, and the GRANT/REVOKE syntax that covers them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.