---
title: Available Scopes
description: OAuth2 scopes available for Agnic authorization
---

# Available Scopes

Scopes define what permissions your application requests from users during OAuth2 authorization.

## Supported Scopes

### payments:sign

```
payments:sign
```

**Description:** Sign X402 authorization proofs on behalf of the user.

**Allows:**
- Signing authorizations within user-defined spending limits
- Using the `/api/sign-payment` endpoint
- Using the `/api/x402/fetch` proxy
- Accessing the AI Gateway (`/v1/chat/completions`)

**Does not allow:**
- Exceeding spending limits
- Transferring funds directly
- Modifying wallet settings

### balance:read

```
balance:read
```

**Description:** View the user's USDC balance.

**Allows:**
- Reading wallet balance via `/api/balance`
- Viewing balance across networks

**Does not allow:**
- Modifying balance
- Initiating transfers

## Default Scopes

If no scope is specified in the authorization request, these scopes are used:

```
payments:sign balance:read
```

## Requesting Scopes

Include scopes in your authorization URL:

```
https://api.agnic.ai/oauth/authorize?
  client_id=your-app
  &redirect_uri=https://yourapp.com/callback
  &state=random_state
  &response_type=code
  &scope=payments:sign+balance:read
```

<Callout type="info">
  Scopes are space-separated in the URL. Use `+` or `%20` for URL encoding.
</Callout>

## Scope Inheritance

When a user re-authorizes your app:
- If requested scopes are a **subset** of previously granted scopes, authorization is automatic
- If you request **new** scopes, the user sees the consent screen again

## Checking Granted Scopes

The token response includes the granted scopes:

```json
{
  "access_token": "agnic_at_abc123...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "payments:sign balance:read"
}
```

Always check that your required scopes were granted before using the token.

## Future Scopes

Additional scopes may be added in the future:

| Scope | Status | Description |
|-------|--------|-------------|
| `transactions:read` | Planned | View transaction history |
| `tokens:manage` | Planned | Create/revoke API tokens |
| `profile:read` | Planned | Read user profile |

## Best Practices

1. **Request minimal scopes** - Only ask for what you need
2. **Explain scope usage** - Tell users why you need each permission
3. **Handle scope changes** - Be prepared for users to deny certain scopes
4. **Check granted scopes** - Verify the token has required permissions

## Next Steps

<Cards>
  <Card title="OAuth2 Integration" href="/docs/authentication/oauth2" />
  <Card title="API Reference" href="/docs/api-reference" />
</Cards>