Authentication

The Flip Utility 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 provide a straightforward way to authenticate. Contact your Flip account manager to obtain API credentials for your utility. Include the key in every request:

Authorization: Bearer fl_your_api_key

API keys are scoped to your organization and grant access to programs, enrollments, and telemetry data within your service territory.

OAuth 2.0 Client Credentials

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

1. Obtain OAuth Client Credentials

Your Flip account manager will provision an OAuth client for your organization, providing 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. 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
• Restrict API key access to authorized personnel within your organization