Authentication

Urblock uses two authentication methods depending on the context: API keys for programmatic access and JWTs for dashboard sessions.

Choosing a Method

Use API keys for server-to-server integration (backends, scripts, CI). Use JWT only for the dashboard UI or when managing API keys programmatically.

API Keys (Resource Endpoints)

All resource endpoints (/v1/tokens, /v1/transactions, /v1/connect, etc.) use API key authentication.

Authorization: Bearer sk_test_abc123...

Key Type	Prefix	Environment	Permissions
Secret key (test)	sk_test_	Testnet	Read + Write
Secret key (live)	sk_live_	Mainnet	Read + Write
Publishable key (test)	pk_test_	Testnet	Read only
Publishable key (live)	pk_live_	Mainnet	Read only

Write operations (deploy, mint, transfer, burn, pause, etc.) require a secret key (sk_). Read-only operations (list, get, balance, etc.) accept either secret or publishable keys.

SDK Example

import { Urblock } from "@urblock/sdk";

// API key from environment
const urblock = new Urblock(process.env.URBLOCK_API_KEY); // sk_test_... or sk_live_...

// All SDK calls use this key automatically
const tokens = await urblock.tokens.list();

curl Example

curl https://api.urblock.io/v1/tokens \
  -H "Authorization: Bearer sk_test_abc123..."

JWT (Dashboard Endpoints)

Dashboard endpoints (/auth/*, /v1/api_keys) use JWT bearer tokens:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Full Auth Flow

// 1. Login to get tokens
const auth = await urblock.auth.login({
  email: "dev@example.com",
  password: "secure-password",
});
// auth = { access_token: "eyJ...", refresh_token: "eyJ...", expires_in: 3600 }

// 2. Use access token for dashboard operations
const keys = await urblock.apiKeys.list();

// 3. Refresh before expiry
const refreshed = await urblock.auth.refresh({
  refresh_token: auth.refresh_token,
});

Token Lifecycle

Token	TTL	Usage
access_token	1 hour	Authenticates dashboard requests
refresh_token	7 days	Obtains new access tokens

warning

Store refresh tokens securely. They can be used to generate new access tokens without credentials.

Scopes

API keys can be restricted to specific scopes for the principle of least privilege:

Scope	Description
tokens:read	List and retrieve tokens
tokens:write	Deploy, pause, unpause tokens
wallets:read	List and retrieve wallets
wallets:write	Create wallets
transactions:read	List and retrieve transactions
transactions:write	Mint, transfer, burn, approve
nfts:read	List and retrieve NFTs
nfts:write	NFT operations
identities:read / identities:write	T-REX identities
compliance:read / compliance:write	T-REX compliance
governance:read / governance:write	Governance operations
roles:read / roles:write	Role management
vesting:read / vesting:write	Vesting operations
vaults:read / vaults:write	Vault operations
webhooks:read / webhooks:write	Webhook management
events:read	Event reading
gas_estimates:read	Gas estimation
batch:write	Batch operations
networks:read	Network listing

Omitting scopes grants full access.

Scope Example

// Create a read-only key for monitoring
const monitorKey = await urblock.apiKeys.create({
  name: "monitoring-readonly",
  scopes: ["tokens:read", "transactions:read", "wallets:read", "events:read"],
});
// This key can list resources but cannot deploy, mint, or transfer

Error Codes

Code	HTTP	Meaning
unauthorized	401	Missing or invalid API key / JWT
token_expired	401	JWT access token has expired
invalid_credentials	401	Wrong email or password
forbidden	403	Key lacks required scope
key_expired	403	API key past expires_at
ip_not_allowed	403	Request IP not in allowed_ips

Best Practices

1. Never expose secret keys — use pk_ keys in client-side code
2. Use scoped keys — grant only the permissions each service needs
3. Rotate keys regularly — use the rotate endpoint for zero-downtime rotation
4. Set expiration — use expires_at for temporary or CI/CD keys
5. Restrict IPs — use allowed_ips for production secret keys
6. Use environment variables — never commit keys to source control

Next Steps

• API Keys API — create, rotate, and manage keys
• Authentication API — login, register, refresh
• Security Model — how keys are stored and protected
• Errors — error handling patterns