Skip to main content

Authentication

The Fuuffy API uses OAuth 2.0 for authentication. This guide explains how to authenticate your requests.

API Environments​

Fuuffy provides separate environments for testing and production:

EnvironmentBase URL
Testinghttps://testing-api-gateway.fuuffy.com/v1
Productionhttps://api-gateway.fuuffy.com/v1

OAuth 2.0 Flow​

Fuuffy implements the Client Credentials grant type, which is ideal for server-to-server authentication.

Authentication Flow​

sequenceDiagram
    participant App as Your Application
    participant Auth as Fuuffy Auth Server
    participant API as Fuuffy API
    
    App->>Auth: POST /oauth/token (client_id, client_secret)
    Auth->>App: access_token
    App->>API: API Request (Bearer token)
    API->>App: API Response

Getting Access Tokens​

Endpoint​

POST https://testing-api-gateway.fuuffy.com/v1/auth/token

Testing Example (cURL)​

curl -X POST https://testing-api-gateway.fuuffy.com/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response​

All successful responses are wrapped in a data object:

{
  "data": {
    "access_token": "sk-418e41a74ca2e7d941fa4456d73dbed7",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}
info

See Standard Response Format for details on Fuuffy's response structure.

Using Access Tokens​

Include the access token in the Authorization header of your API requests.

cURL Example (Testing)​

curl https://testing-api-gateway.fuuffy.com/v1/orders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Expiration​

Access tokens expire after 1 hour (3600 seconds). When a token expires, you'll receive a 401 Unauthorized response:

{
  "error": {
    "code": "invalid_token",
    "message": "The access token expired",
    "details": "Please request a new access token"
  }
}

Best Practices​

  1. Cache tokens - Store the token and reuse it until it expires
  2. Refresh proactively - Request a new token before the current one expires
  3. Handle 401 errors - Automatically request a new token when you receive a 401 response

Security Best Practices​

Keep Your Credentials Safe

Never expose your client_secret in client-side code or public repositories.

  1. Store credentials securely - Use environment variables or secure vaults
  2. Use HTTPS only - All API requests must use HTTPS
  3. Rotate credentials regularly - Update your credentials periodically
  4. Monitor API usage - Watch for unusual activity
  5. Implement rate limiting - Respect API rate limits

Next Steps​