Skip to main content
Cobee’s API is built with security as a foundational principle, ensuring that sensitive data is safeguarded and that only authorized users can access specific resources. This document outlines the key security mechanisms and protocols implemented across the Cobee API.

​
Authentication & Authorization

​
OAuth 2.0 with OpenID Connect

The Cobee API uses the OAuth 2.0 protocol for authentication and authorization, enabling secure access to resources without exposing user credentials. For server-to-server integrations, the Client Credentials grant type is used, combined with OpenID Connect (OIDC) for standardized identity claims. Each integration is provisioned with a dedicated machine-to-machine (M2M) application in our Auth0 tenant. This provides a client_id and client_secret, which can be used to obtain an access token from the /oauth/token endpoint.

​
JSON Web Tokens (JWT)

Access to Cobee’s API requires including a JWT (JSON Web Token) in the Authorization header of each request. These tokens are issued by Auth0 upon successful authentication. Cobee’s JWTs adhere to the OIDC standard and include:
  • Standard claims such as iss (issuer), sub (subject), aud (audience), iat, exp, azp (authorized party), and gty (grant type).
  • Custom claims under a namespaced key, for example:
{
  "https://auth.cobee.io/metadata": {
    "companyId": "5e9e9701-9883-447d-9884-46e75993e33b"
  }
}
All tokens are signed using RS256 and validated against our Auth0 public keys.

​
Secret Management

Access credentials (client_id and client_secret) are securely managed via Auth0. These secrets should never be stored in plaintext and must be managed according to industry best practices
  • Store secrets securely in your application’s secret manager or environment variables.
  • Never expose secrets in client-side code or version control.

​
Access Control & Scoping

Authorization is strictly enforced via structured claims embedded in the JWT. Each token includes:
  • companyId: Grants access to resources belonging to a specific company.
  • corporationId (optional): Included only for clients with access to multiple companies within a corporation.
Access control is validated on every request, ensuring that users and services can only retrieve data within their authorized scope.