Skip to main content

Your First API Call

Learn how to make your first authenticated API call to DPaaS.

Overview​

This guide walks you through:

  1. Authenticating to get a JWT token
  2. Making an authenticated API call
  3. Creating a resource
  4. Handling responses

Prerequisites​

Before you begin
  • You have DPaaS running locally or access to a DPaaS instance
  • You have cURL or an HTTP client installed
  • You have created a user account and organization

Step 1: Get an Access Token​

First, authenticate to obtain a JWT access token:

curl -X POST http://localhost:8000/authentication/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "organization_slug": "myorg"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlkIiwi...",
  "refresh_token": "def502004a8c...",
  "token_type": "Bearer",
  "expires_in": 900
}
Important

The access_token expires in 15 minutes (900 seconds). Use the refresh_token to get a new one without re-authenticating.

Step 2: Make an API Call​

Now use the access token to make an authenticated request. Let's list your accounts:

curl http://localhost:8000/accounts \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "total": 2,
  "page": 1,
  "results": [
    {
      "id": "acc-123",
      "name": "Production",
      "organization_id": "org-456",
      "is_default": false,
      "is_active": true,
      "created_at": "2025-09-30T10:00:00Z",
      "updated_at": "2025-09-30T10:00:00Z"
    },
    {
      "id": "acc-789",
      "name": "Development",
      "organization_id": "org-456",
      "is_default": true,
      "is_active": true,
      "created_at": "2025-09-30T09:00:00Z",
      "updated_at": "2025-09-30T09:00:00Z"
    }
  ]
}

Step 3: Create a Resource​

Let's create a new account:

curl -X POST http://localhost:8000/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "is_default": false
  }'

Response:

{
  "id": "acc-new123",
  "name": "Staging",
  "organization_id": "org-456",
  "is_default": false,
  "is_active": true,
  "created_at": "2025-09-30T11:00:00Z",
  "updated_at": "2025-09-30T11:00:00Z"
}

Understanding the Response Format​

All DPaaS list endpoints follow a consistent format:

{
  "total": 10,        // Total number of items
  "page": 1,          // Current page number
  "results": [...]    // Array of items for this page
}

Pagination​

Control pagination with query parameters:

curl "http://localhost:8000/accounts?page=1&quantity=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  • page: Page number (default: 1)
  • quantity: Items per page (default: 20, max: 100)
  • order_by: Sort field (prefix with - for descending, e.g., -created_at)

Error Handling​

DPaaS returns standard HTTP status codes and JSON error responses:

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Solution: Get a new access token using your refresh token.

403 Forbidden​

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Solution: Check that your account has the required permissions.

422 Validation Error​

{
  "error": "ValidationError",
  "message": "Invalid input",
  "details": {
    "name": ["This field is required"]
  }
}

Solution: Check the details object for specific field errors.

Refreshing Your Token​

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

curl -X POST http://localhost:8000/authentication/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "def502004a8c..."
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "abc123def456...",  // New refresh token
  "token_type": "Bearer",
  "expires_in": 900
}
Token Rotation

Refresh tokens are automatically rotated on each use. The old refresh token becomes invalid after a new one is issued.

Next Steps​

Now that you know the basics:

Common Patterns​

Making Multiple Calls​

# Store token in a variable
TOKEN=$(curl -X POST http://localhost:8000/authentication/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass", "organization_slug": "myorg"}' \
  | jq -r '.access_token')

# Use it for subsequent requests
curl http://localhost:8000/accounts \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8000/users \
  -H "Authorization: Bearer $TOKEN"

Working with Python​

import requests

# Authenticate
response = requests.post(
    "http://localhost:8000/authentication/login",
    json={
        "email": "[email protected]",
        "password": "your-password",
        "organization_slug": "myorg"
    }
)
token = response.json()["access_token"]

# Make authenticated requests
headers = {"Authorization": f"Bearer {token}"}

# List accounts
accounts = requests.get(
    "http://localhost:8000/accounts",
    headers=headers
).json()

print(f"Found {accounts['total']} accounts")
for account in accounts['results']:
    print(f"  - {account['name']}")
info

For production applications, consider using the official Python SDK which handles authentication and token refresh automatically.