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

# nsc token create

Create a revokable token with specific permissions and expiration.

`nsc token create` provides commands to manage revokable tokens that can be used for authentication in situations where federation is not available or practical. These tokens provide a flexible way to grant time-limited, scoped access to resources without using full workload federation.

Revokable tokens are useful for:

* CI/CD pipelines that don't support OIDC federation
* Local development and testing
* Automated scripts and tools
* Temporary access grants with expiration
* Situations requiring explicit permission scoping

`nsc token create` generates a new revokable token that can be used for authentication. Tokens can be scoped to specific resources and actions, and can be configured with custom expiration times.

## Usage

```bash theme={null}
nsc token create [flags]
```

### Examples

**Create a token with a name, description, and grant:**

```bash theme={null}
nsc token create \
  --name "ci-pipeline-token" \
  --description "Token for GitHub Actions CI pipeline" \
  --grant '{"resource_type":"github/runner-profile","resource_id":"*","actions":["*"]}'
```

**Create a token with custom expiration:**

```bash {4} theme={null}
nsc token create \
  --name "short-lived-builder-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --expires_in 1h
```

**Create a token with specific permissions:**

```bash {3,4} theme={null}
nsc token create \
  --name "builder-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --grant '{"resource_type":"artifact","resource_id":"*","actions":["create","resolve","list"]}'
```

**Save token to file for automated usage:**

```bash {4} theme={null}
nsc token create \
  --name "automation-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --token_file token.json
```

**Display only the token value:**

```bash {4} theme={null}
nsc token create \
  --name "quick-token" \
  --grant '{"resource_type":"builder","resource_id":"*","actions":["ensure","access"]}' \
  --output token
```

**Use the token with the `nsc` CLI:**

Write the token to a file with `--token_file`, then point the `NSC_TOKEN_FILE`
environment variable at it. The `nsc` CLI reads this variable on every
invocation and authenticates with the token instead of your local login.

#### 1. Create a token

Create a token and save it to a file:

```bash theme={null}
nsc token create \
  --name "cli-token" \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","destroy"]}' \
  --token_file token.json
```

#### 2. Set the NSC\_TOKEN\_FILE environment variable

Set the NSC\_TOKEN\_FILE environment variable to point to the token file, to use the token for subsequent nsc CLI commands.

```bash theme={null}
NSC_TOKEN_FILE="./token.json" nsc instance list
```

## Flags

### --name string

A unique name for the token within the tenant. This helps identify the token's purpose when listing or managing tokens.

### --grant stringArray (can be repeated)

Grant specific permissions to the token as a JSON object. This flag can be specified multiple times to grant multiple permissions.

**Format:**

```json theme={null}
{"resource_type":"...","resource_id":"...","actions":["..."]}
```

See [Permissions](https://namespace.so/docs/security/permissions.md) for the full list of available resource types and actions.

### --description string (optional)

A human-readable description of the token's purpose. Use this to document why the token was created and what it's used for.

### --expires\_in duration (optional)

Duration until the token expires. The default is 24 hours. Maximum allowed duration is 365 days.

Available time units are: `h` (hours), `d` (days),`w` (weeks), and `y` (years).

**Examples:**

* `1h` - 1 hour
* `24h` - 24 hours (default)
* `7d` - 7 days
* `1w` - 1 week, same as `7d`
* `1y` - 1 year (maximum), same as `365d`

### --user (optional)

Scope the token to the current user's workspace membership. By default, creating tokens requires the user to be a workspace admin.
When `--user` is specified, the token is bound to the calling user's membership, allowing non-admin users to create tokens scoped to their own permissions.

### --no\_expiry (optional)

If specified, the token will be created with unlimited duration, overriding the default. Must be used together with `--user`. Only user-bound tokens may have no expiration set.

### --output string (optional)

Output format for the created token. Options: `table` (default), `json`, `token`.

* **table**: Display token information in a formatted table
* **json**: Output full token details as JSON
* **token**: Output only the token value (useful for scripts)

### --token\_file string (optional)

Write the token to the specified file in JSON format. This is useful for automated workflows that need to store and reuse the token.

To authenticate the `nsc` CLI (or any Namespace SDK) with the saved token, set the `NSC_TOKEN_FILE` environment variable to the file's path:

```bash theme={null}
export NSC_TOKEN_FILE="$(pwd)/token.json"
nsc instance list
```

The CLI reads the credential from this file on each invocation. Note that `NSC_TOKEN_FILE` expects a *path to a token file*, not a raw token value.

## Related Topics

* [nsc token list](https://namespace.so/docs/reference/cli/token-list.md) - List existing tokens
* [nsc token refresh](https://namespace.so/docs/reference/cli/token-refresh.md) - Extend a token's lifetime
* [nsc token revoke](https://namespace.so/docs/reference/cli/token-revoke.md) - Revoke tokens
* [Workspace Access Controls](https://namespace.so/docs/workspaces/access.md) - Permission management
* [Workload Federation](https://namespace.so/docs/federation.md) - Federation with cloud providers
* [Security](https://namespace.so/docs/workspaces/security.md) - Security best practices and audit logging


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