Authentication

The Flip OEM API uses OAuth 2.0 and API keys to authenticate requests. All API requests must include a valid credential in the Authorization header.

API Keys

API keys are the simplest way to authenticate. Create an API key from the Developer Console and include it in every request:

Authorization: Bearer fl_your_api_key

API keys are scoped to your organization and grant access to all sites and devices managed by your OEM tenant. Keep your API keys secure and never expose them in client-side code or public repositories.

OAuth 2.0 Client Credentials

For server-to-server integrations, you can use the OAuth 2.0 client credentials flow to obtain short-lived access tokens.

1. Create an OAuth Client

Register an OAuth client in the Developer Console. You will receive a client_id and client_secret.

2. Request an Access Token

Exchange your client credentials for an access token:

curl -X POST https://oauth.flip.energy/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"

The response includes an access token and its expiration time:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Use the Access Token

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

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Management

Access tokens expire after the duration specified in expires_in (in seconds). Your integration should:

• Cache the access token and reuse it until it is close to expiring
• Request a new token before the current one expires (e.g., refresh when 80% of the TTL has elapsed)
• Handle 401 Unauthorized responses by requesting a fresh token and retrying the request

Environments

Use the sandbox environment during development and testing. API keys and OAuth clients work across both environments.

Security Best Practices

• Store credentials in environment variables or a secrets manager, never in source code
• Rotate API keys periodically and revoke any compromised keys immediately
• Use the principle of least privilege when configuring OAuth client scopes
• Always use HTTPS for all API communication