> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partners.api.cobee.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

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 <a href="api-reference/authentication/endpoint/post_authenticate" target="_self">`/oauth/token`</a> 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:

<CodeGroup>
  ```json theme={null}
  {
    "https://auth.cobee.io/metadata": {
      "companyId": "5e9e9701-9883-447d-9884-46e75993e33b"
    }
  }
  ```
</CodeGroup>

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.