> ## 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.

# Projects

A project is a boundary inside an organization that groups resources, such as `prod` and `staging`. Grants, scopes, and guardrails can then say where a role or a statement applies.

> [!WARNING]
>
> **Preview.** Not available yet.

Projects are optional. An organization that never creates one keeps everything in `default` and can ignore projects entirely. Leaving `projects` out of a grant or a statement means every project, and every rule works the same either way.

## What Sits in a Project

* Only resources sit in projects. Users, service accounts, and roles belong to the organization, and a grant says which projects each one reaches.
* Each resource sits in exactly one project. That makes a project a boundary, not a tag. Access given in `staging` never reaches a resource in `prod`.
* Projects sit directly under the organization and do not nest. They are never a billing unit. [Managed organizations](https://developers.telnyx.com/docs/iam/access/delegations.md) are for separate bills.

## Setting Projects Up

1. Create the project. Someone holding `iam.projects.create`, such as an Org Admin, names it.
2. Build new resources into it. The product's own create request names the project, and the requester needs permission in that project. A resource created without one lands in `default`.
3. Move existing resources in. Moving a resource needs permission in both its old and its new project, so nobody can pull a resource out of `prod` without access to `prod`.

```json theme={null}
POST /v2/iam/projects
{ "name": "prod" }

POST /v2/messaging_profiles
{ "name": "Appointment reminders", "project": "prod" }

POST /v2/iam/projects/prod/resources
{ "resources": ["network/net_8f3a"] }
```

## Where Projects Are Used

* In a [grant](https://developers.telnyx.com/docs/iam/access/grants.md), a role applies only to resources in the named projects.
* In a [scope](https://developers.telnyx.com/docs/iam/credentials/scoped-keys.md), an API key is held to the named projects, even when its user reaches further.
* In a [guardrail](https://developers.telnyx.com/docs/iam/access/guardrails.md), a deny protects a project from everyone, the owner included.
* In lists, such as `GET /v2/phone_numbers`, a request returns only resources in projects the requester may read.

```json theme={null}
POST /v2/iam/grants
{
  "role_id": "<messaging-dev>",
  "principal_type": "group",
  "principal_id": "okta/messaging-team",
  "projects": ["staging"]
}

POST /v2/iam/grants
{
  "role_id": "<Read-only>",
  "principal_type": "group",
  "principal_id": "okta/messaging-team",
  "projects": ["prod"]
}
```

The messaging team builds in `staging` and only reads `prod`.
