> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# API Authentication

NVIDIA DSX Air uses NGC API keys for authenticating API requests. This page covers Air-specific authentication details. For general information about NGC API keys, see the [NGC API Keys documentation](https://docs.nvidia.com/ngc/latest/ngc-user-guide.html#ngc-api-keys).

For the full API reference, navigate the [API reference](/api-reference).

## API Key Types

NGC supports two types of API keys:

| Key Type         | Use Case                        | Lifecycle                    |
| ---------------- | ------------------------------- | ---------------------------- |
| **Personal Key** | Individual development, testing | Tied to user account         |
| **Service Key**  | Automation, CI/CD pipelines     | Tied to NGC org (not a user) |

For most Air API usage, a Personal Key is sufficient. Use Service Keys when you need automation that shouldn't depend on an individual user's account.

### Generating API Keys

To generate an API key:

* **Personal Key**: See [Generating a Personal API Key](https://docs.nvidia.com/ngc/latest/ngc-user-guide.html#generating-a-personal-api-key)
* **Service Key**: See [Generating a Service API Key](https://docs.nvidia.com/ngc/latest/ngc-user-guide.html#generating-a-service-api-key)

When generating a key, select **NVIDIA Air** from the services list to grant Air API access.

## Using API Keys

Include your API key in the `Authorization` header:

```
curl -X GET "https://api.dsx-air.nvidia.com/api/v3/simulations/" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Roles and Scopes

Air uses a role-based access control system managed through NGC. The Air API checks **scopes** to authorize requests. How you get scopes depends on the key type:

* **Personal API Keys**: You assign **roles** to users in NGC. Air automatically derives scopes from those roles.
* **Service Keys**: You assign **scopes** directly when creating the key, giving you fine-grained control.

### Roles

Roles are assigned to users in your NGC organization and apply to Personal API Keys. To manage user roles, see [Updating User Roles](https://docs.nvidia.com/ngc/latest/ngc-user-guide.html#updating-user-roles) in the NGC documentation.

| Role                  | Description                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `air_user`            | Standard Air user with full simulation access                                                     |
| `air_org_admin`       | Organization-wide access with the same permissions as `air_user`, applied across the organization |
| `air_instructor`      | Can create and manage training sessions                                                           |
| `air_demo_manager`    | Can create, edit, and publish Demo Marketplace content                                            |
| `air_image_uploader`  | Can upload and edit custom images                                                                 |
| `air_image_publisher` | Can upload, edit, and publish images for public availability                                      |
| `air_image_sharer`    | Can create cross-org image sharing links                                                          |
| `air_image_claimer`   | Can claim images shared from another organization                                                 |

### Scopes

Scopes are the permissions that the Air API checks to authorize requests. For Personal API Keys, scopes are derived from assigned roles. For Service Keys, you select scopes directly when generating the key.

| Scope                          | Description                                                        |
| ------------------------------ | ------------------------------------------------------------------ |
| `air:simulation_read`          | Read simulation details, nodes, interfaces, services               |
| `air:simulation_create`        | Create simulations via import, clone, or UI                        |
| `air:simulation_edit`          | Modify simulation properties and topology                          |
| `air:simulation_delete`        | Delete simulations                                                 |
| `air:simulation_start_stop`    | Start and stop simulations                                         |
| `air:image_read`               | View published and org images                                      |
| `air:image_write`              | Upload and edit images                                             |
| `air:image_publish`            | Publish images for public availability (not restricted to any org) |
| `air:image_sharing`            | Create cross-org image share links                                 |
| `air:image_claiming`           | Claim images shared from another organization                      |
| `air:marketplace_demo_write`   | Create and edit marketplace demos                                  |
| `air:marketplace_demo_publish` | Publish demos to the marketplace                                   |
| `air:training_instructor`      | Create and manage training sessions                                |

### Role to Scope Mapping

Each role grants the following scopes:

| Role                  | Scopes                                                                                                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `air_user`            | `air:simulation_read`, `air:simulation_create`, `air:simulation_edit`, `air:simulation_delete`, `air:simulation_start_stop`, `air:image_read`, `air:marketplace_demo_write` |
| `air_org_admin`       | Same scopes as `air_user`                                                                                                                                                   |
| `air_instructor`      | `air:training_instructor`                                                                                                                                                   |
| `air_demo_manager`    | `air:marketplace_demo_write`, `air:marketplace_demo_publish`                                                                                                                |
| `air_image_uploader`  | `air:image_read`, `air:image_write`                                                                                                                                         |
| `air_image_publisher` | `air:image_read`, `air:image_write`, `air:image_publish`                                                                                                                    |
| `air_image_sharer`    | `air:image_sharing`                                                                                                                                                         |
| `air_image_claimer`   | `air:image_claiming`                                                                                                                                                        |