API Authentication

NFYio supports multiple authentication methods for API access: API Keys, JWT tokens (OAuth 2.0), and refresh tokens. Choose the method that fits your use case—CLI scripts, server-side apps, or user-facing applications.

Authentication Methods

Method	Use Case	Lifetime
API Key	Server-to-server, CLI, scripts	Until revoked
JWT (OAuth 2.0)	User sessions, web/mobile apps	Short-lived (e.g., 1h)
Refresh Token	Obtain new JWTs without re-login	Long-lived

API Keys

API keys are the simplest way to authenticate. Create one in the NFYio dashboard or via API, then pass it in the Authorization header.

Creating an API Key

Via Dashboard: Settings → Access Keys → Create Key

Via API:

curl -X POST https://api.yourdomain.com/v1/access-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "scopes": ["read:objects", "write:objects", "read:buckets"]
  }'

Response:

{
  "id": "ak_abc123xyz",
  "secret": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "production-server",
  "scopes": ["read:objects", "write:objects", "read:buckets"],
  "created_at": "2026-03-01T12:00:00Z"
}

Important: The secret is shown only once. Store it securely (e.g., in a secrets manager).

Using an API Key

curl -X GET https://api.yourdomain.com/v1/buckets \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Or with the X-API-Key header:

curl -X GET https://api.yourdomain.com/v1/buckets \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Scopes & Permissions

Control what an API key can do with scopes:

Scope	Description
read:objects	List and download objects
write:objects	Upload, delete, copy objects
read:buckets	List buckets and metadata
write:buckets	Create, delete, configure buckets
read:agents	Query agents, list threads
write:agents	Create agents, manage embeddings
read:networking	List VPCs, subnets, security groups
write:networking	Create/update networking resources
admin	Full access (use sparingly)

Example: A backup script might need only read:objects and read:buckets.

JWT Tokens (OAuth 2.0)

For user-facing apps, use OAuth 2.0 to obtain JWT access tokens. JWTs are short-lived and include user/role claims.

Obtaining a JWT

Password grant (server-side, trusted clients):

curl -X POST https://api.yourdomain.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "username=user@example.com" \
  -d "password=user_password"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Using a JWT

curl -X GET https://api.yourdomain.com/v1/buckets \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh Tokens

When the access token expires, use the refresh token to get a new one:

curl -X POST https://api.yourdomain.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "refresh_token=rt_xxxxxxxxxxxxxxxx"

AWS SDK Configuration

For S3-compatible storage, use the AWS SDK with your NFYio endpoint and credentials:

const { S3Client, ListBucketsCommand } = require('@aws-sdk/client-s3');

const client = new S3Client({
  region: 'us-east-1',
  endpoint: 'https://storage.yourdomain.com',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY_ID',      // From NFYio access keys
    secretAccessKey: 'YOUR_SECRET_ACCESS_KEY',
  },
  forcePathStyle: true,
});

const { Buckets } = await client.send(new ListBucketsCommand({}));
console.log(Buckets);

Python (boto3):

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://storage.yourdomain.com',
    aws_access_key_id='YOUR_ACCESS_KEY_ID',
    aws_secret_access_key='YOUR_SECRET_ACCESS_KEY',
    region_name='us-east-1',
    config=boto3.session.Config(signature_version='s3v4'),
)

buckets = s3.list_buckets()
print(buckets['Buckets'])

Security Best Practices

1. Never commit secrets — Use environment variables or a secrets manager
2. Rotate keys regularly — Create new keys and revoke old ones periodically
3. Least privilege — Assign only the scopes an app needs
4. Use JWTs for users — Prefer OAuth/JWT for user sessions over long-lived API keys
5. HTTPS only — Never send credentials over plain HTTP
6. Monitor usage — Watch for unusual API patterns that may indicate compromise

Next Steps

• Storage API Reference — S3 and REST endpoints
• Error Handling — Handling 401, 403, and other errors
• Rate Limits — Understanding request limits