> ## 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.
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
```
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](/docs/security/permissions) 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](/docs/reference/cli/token-list) - List existing tokens
* [nsc token refresh](/docs/reference/cli/token-refresh) - Extend a token's lifetime
* [nsc token revoke](/docs/reference/cli/token-revoke) - Revoke tokens
* [Workspace Access Controls](/docs/workspaces/access) - Permission management
* [Workload Federation](/docs/federation) - Federation with cloud providers
* [Security](/docs/workspaces/security) - Security best practices and audit logging