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

# Users

A user is a person in the organization. Every request a user sends, with a session, an API key, or an OAuth token, is decided by the roles granted to that user.

## Identity

A user is identified by the `id` the [Organization Users API](https://developers.telnyx.com/api-reference/organization-users/list-organization-users.md) returns, and that ID is the `principal_id` of a grant.

```json GET /v2/organizations/users theme={null}
{
  "data": [
    {
      "id": "3b52b5e6-f289-45a9-8543-3a86d0e1ae1b",
      "email": "user@example.com",
      ...
    }
  ],
  ...
}
```

The [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) is not in this list and cannot hold a grant.

## Grants

Each [grant](https://developers.telnyx.com/docs/iam/access/grants.md) gives a user one [role](https://developers.telnyx.com/docs/iam/access/roles.md). A user can hold up to ten roles, and their statements add up.

```json POST /v2/iam/grants theme={null}
{
  "role_id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
  "principal_type": "user",
  "principal_id": "3b52b5e6-f289-45a9-8543-3a86d0e1ae1b"
}
```

Once the organization has [enabled IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md), a user without a grant is refused every action. Until then, a user keeps the permissions managed in Mission Control Portal, and grants have no effect.

The [permission groups](https://developers.telnyx.com/docs/iam/permission-groups.md) in Mission Control Portal keep applying to a user on top of the user's roles, until they retire.

## Credentials

Whatever credential a user presents, IAM decides the request for the user.

* A session, after signing in to Mission Control Portal.
* An [API key](https://developers.telnyx.com/docs/development/api-fundamentals/create-api-keys.md) the user created.
* An OAuth token an application holds for the user, such as the [Telnyx CLI](https://developers.telnyx.com/docs/development/cli.md). The scope approved for that application still narrows the request after IAM allows it.

A credential proves who the user is. It never augments what the user's roles allow. See [Credentials](https://developers.telnyx.com/docs/iam/credentials.md).

## Groups

Preview A grant also names a [group](https://developers.telnyx.com/docs/iam/principals/groups.md) of the organization's identity provider, so access follows group membership.
