Skip to main content

API Authentication

The CO2Trust API uses JWT (JSON Web Tokens) for authentication. Most endpoints require authentication, except for public endpoints like health checks and public product listings.

Authentication Flow​

1. User Authentication​

Authenticate a user to receive an access token:

Endpoint: POST /co2trust-services/v1/users/auth

Headers:

X-Backend-Secret-Key: <your-backend-secret-key>
Content-Type: application/json

Request Body:

{
  "id": "user-id",
  "email": "user@example.com",
  "address": "0x5e0ecE948c0920d7670827b29a798f6F0C2C4ca1"
}

Response:

{
  "id": "user-id",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_type": "bearer",
  "is_admin": false,
  "is_approver": false
}

2. Using the Access Token​

Include the access token in the Authorization header for authenticated requests:

Authorization: Bearer <access_token>

Example:

curl -X GET "https://api.testnet.co2trust.earth/co2trust-services/v1/nfts/user" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration​

Access tokens expire after a configured period (default: set by ACCESS_TOKEN_EXPIRE_MINUTES environment variable). When a token expires, you'll receive a 401 Unauthorized response and need to authenticate again.

User Roles​

The API supports role-based access control:

  • Regular User: Standard access to user-specific endpoints
  • Admin (is_admin: true): Administrative access to system endpoints
  • Approver (is_approver: true): Access to approval workflows

Backend Secret Key​

The authentication endpoint requires a X-Backend-Secret-Key header. This key is configured server-side and must match the BACKEND_SECRET_KEY environment variable.

Note: This is a server-side security measure. The backend secret key should never be exposed in client-side code.

Public Endpoints​

The following endpoints do not require authentication:

  • GET / - Root endpoint
  • GET /health - Health check
  • GET /co2trust-services/v1/products - Public product listings (when is_public: true)
  • GET /co2trust-services/v1/suppliers - Public supplier listings

Error Responses​

Invalid Token​

{
  "detail": "Could not validate credentials"
}

Status Code: 401

Missing Token​

{
  "detail": "Not authenticated"
}

Status Code: 401

Invalid Backend Secret Key​

{
  "detail": "Invalid key"
}

Status Code: 401

Security Best Practices​

  1. Never expose tokens: Store tokens securely and never commit them to version control
  2. Use HTTPS: Always use HTTPS in production to protect tokens in transit
  3. Token rotation: Implement token refresh mechanisms for long-lived applications
  4. Validate tokens: Always validate tokens on the client side before making requests
  5. Handle expiration: Implement proper error handling for expired tokens

Next Steps​