Authentication & Security

There are two ways to authenticate requests to the Flowcase API: API keys and OAuth2 client credentials. Choose one method per integration.

Getting an API Key

API keys are essential for authenticating your requests to the Flowcase API.

Creation Process

1. Log in to <subdomain>.flowcase.com with an administrator account.
2. Navigate to Account → API Keys.
3. Click Create New API Key to generate a new key.

Authentication

Include the API key in the Authorization header of your HTTP requests. Both of these header formats are accepted:

Authorization: Bearer <your-api-key>

Authorization: Token token="<your-api-key>"

For example:

curl -i -X GET 'https://<subdomain>.flowcase.com/api/v2/users/search' \
  --header 'Authorization: Bearer <your-api-key>'

HTTP/2 200
date: Tue, 15 Oct 2024 21:12:00 GMT
content-type: application/json; charset=utf-8
...
x-request-id: 2bb8dbe6-442e-4d2c-9cf2-8f2c41449f31

[...]

OAuth2 Client Credentials

Creation Process

1. Log in to <subdomain>.flowcase.com with an administrator account.
2. Navigate to Account → OAuth2 clients.
3. Click + New OAuth2 client to generate a new client credential.
4. Make a note of the Client ID and Client Secret. The Client Secret is shown once only. If you lose it, you must regenerate it.

Requesting an access token

Exchange the Client ID and Client Secret for a short-lived access token:

curl -i -X POST "https://<subdomain>.flowcase.com/auth/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id="<CLIENT_ID>" \
  -d client_secret="<CLIENT_SECRET>"

The response returns the token and its lifetime:

{
  "access_token": "flowcase_oat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 600,
  "created_at": 1771286400
}

Using the access token

Send the access_token in the Authorization header of each request:

Authorization: Bearer <access_token>

For example, to request a list of all users in your company:

curl -i "https://<subdomain>.flowcase.com/api/v2/users/search" \
  --header "Authorization: Bearer flowcase_oat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Renewing an access token

An access token is valid for 600 seconds (10 minutes). Once it expires, requests fail with a 401:

{"error":"invalid_token","error_description":"The access token is invalid, expired or revoked"}

When this happens, request a new access token with your Client ID and Client Secret. Track the expiry time and renew the token before it expires, rather than waiting for the 401 response.

Best Practices

HTTPS

All requests must use https. Requests to http will be redirected, but the initial plaintext request may expose your credentials, so always use https directly.

Naming Conventions

• Use clear, descriptive names unique within your organisation.
• Include environment (e.g. prod, dev, staging), integration name, and a unique identifier.
• Example: INTEGRATION_HUBSPOT_PROD_001

Technical Contact

• Assign a technical contact for each API key or OAuth2 client, the developer or administrator responsible for that integration.
• Keep contact information up to date.

Access Rights

• Apply the principle of least privilege: grant only the minimum permissions necessary.
• Regularly review and adjust permissions.

Security

• Use different credentials for different applications or integrations.
• Never embed credentials directly in code, use environment variables or a secret manager.
• Avoid committing credentials to version control.

Key Rotation

• Rotate API keys and OAuth2 client secrets at least annually.
• Deactivate unused credentials promptly.
• Plan for smooth transitions when rotating credentials in live integrations.