> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get up and running with Grantex in under 5 minutes.
## 1. Install the SDK
```bash npm theme={null}
npm install @grantex/sdk
```
```bash pip theme={null}
pip install grantex
```
```bash CLI theme={null}
npm install -g @grantex/cli
grantex config set --url https://api.grantex.dev --key YOUR_API_KEY
```
## 2. Register your agent
```typescript TypeScript theme={null}
import { Grantex } from '@grantex/sdk';
const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });
const agent = await grantex.agents.register({
name: 'travel-booker',
description: 'Books flights and hotels on behalf of users',
scopes: ['calendar:read', 'payments:initiate:max_500', 'email:send'],
});
console.log(agent.did);
// → did:grantex:ag_01HXYZ123abc...
```
```python Python theme={null}
from grantex import Grantex
client = Grantex(api_key=os.environ["GRANTEX_API_KEY"])
agent = client.agents.register(
name="travel-booker",
scopes=["calendar:read", "payments:initiate:max_500", "email:send"],
description="Books flights and hotels on behalf of users",
)
print(agent.did)
# → did:grantex:ag_01HXYZ123abc...
```
```bash CLI theme={null}
grantex agents register \
--name travel-booker \
--description "Books flights and hotels on behalf of users" \
--scopes calendar:read,payments:initiate:max_500,email:send
```
## 3. Request authorization from a user
```typescript TypeScript theme={null}
const authRequest = await grantex.authorize({
agentId: agent.id,
userId: 'user_abc123',
scopes: ['calendar:read', 'payments:initiate:max_500'],
expiresIn: '24h',
redirectUri: 'https://yourapp.com/auth/callback',
});
// Redirect user to the consent page
console.log(authRequest.consentUrl);
// → https://consent.grantex.dev/authorize?req=eyJ...
```
```python Python theme={null}
auth = client.authorize(
agent_id=agent.id,
user_id="user_abc123",
scopes=["calendar:read", "payments:initiate:max_500"],
)
# Redirect user to the consent page
print(auth.consent_url)
```
```bash CLI theme={null}
grantex authorize \
--agent ag_01HXYZ... \
--principal user_abc123 \
--scopes calendar:read,payments:initiate:max_500
# Sandbox mode returns the code directly
```
## 4. Exchange the code for a grant token
After the user approves, your redirect URI receives an authorization `code`. Exchange it for a signed grant token:
```typescript TypeScript theme={null}
const token = await grantex.tokens.exchange({
code, // from the redirect callback
agentId: agent.id,
});
console.log(token.grantToken); // RS256 JWT — pass this to your agent
console.log(token.scopes); // ['calendar:read', 'payments:initiate:max_500']
console.log(token.grantId); // 'grnt_01HXYZ...'
```
```python Python theme={null}
from grantex import ExchangeTokenParams
token = client.tokens.exchange(ExchangeTokenParams(
code=code,
agent_id=agent.id,
))
print(token.grant_token) # RS256 JWT
print(token.scopes) # ('calendar:read', 'payments:initiate:max_500')
print(token.grant_id) # 'grnt_01HXYZ...'
```
```bash CLI theme={null}
grantex tokens exchange --code --agent-id ag_01HXYZ...
# Returns grantToken (JWT), refreshToken, grantId, scopes
```
## 5. Verify the token offline
```typescript TypeScript theme={null}
import { verifyGrantToken } from '@grantex/sdk';
const grant = await verifyGrantToken(token.grantToken, {
jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
requiredScopes: ['calendar:read'],
});
console.log(grant.principalId); // 'user_abc123'
console.log(grant.scopes); // ['calendar:read', 'payments:initiate:max_500']
```
```python Python theme={null}
from grantex import verify_grant_token, VerifyGrantTokenOptions
grant = verify_grant_token(token.grant_token, VerifyGrantTokenOptions(
jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
))
print(grant.principal_id) # 'user_abc123'
print(grant.scopes) # ('calendar:read', 'payments:initiate:max_500')
```
```bash CLI theme={null}
grantex tokens verify
# Shows: valid, grantId, scopes, principal, agent, expiresAt
```
## 6. Log every action
```typescript TypeScript theme={null}
await grantex.audit.log({
agentId: agent.id,
grantId: token.grantId,
action: 'payment.initiated',
status: 'success',
metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});
```
```python Python theme={null}
client.audit.log(
agent_id=agent.id,
grant_id=token.grant_id,
action="payment.initiated",
status="success",
metadata={"amount": 420, "currency": "USD", "merchant": "Air India"},
)
```
```bash CLI theme={null}
grantex audit log \
--agent-id ag_01HXYZ... \
--agent-did did:grantex:ag_01HXYZ... \
--grant-id grnt_01HXYZ... \
--principal-id user_abc123 \
--action payment.initiated \
--status success \
--metadata '{"amount":420,"currency":"USD","merchant":"Air India"}'
```
## Next steps
Learn about the three primitives: agent identity, delegated grants, and audit trails.
Run the full stack locally with Docker Compose and sandbox mode.
Full API reference for the TypeScript SDK.
Full API reference for the Python SDK.
83 commands with --json support for scripting and AI agents.