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

# Autenticar solicitudes de la API de Orbit con claves y tokens

> Autentica las solicitudes de la API de Orbit con claves de API para llamadas de servidor a servidor o tokens de sesión Bearer, además de SSO SAML para los usuarios empresariales del panel.

# Autenticación

Orbit autentica las **solicitudes de API** de dos maneras: una clave de API para
llamadas de servidor a servidor, y un token Bearer de sesión para los usuarios
del panel. Las organizaciones empresariales pueden, además, iniciar sesión de
sus usuarios mediante [el inicio de sesión único SAML](#single-sign-on-saml)
y aprovisionarlos mediante [SCIM](#directory-provisioning-scim). Elige el método
que se ajuste a cómo se realiza la solicitud.

## Clave de API (servidor a servidor)

Incluye tu clave de API en el encabezado `X-API-Key`:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## Token Bearer (usuarios del panel)

Para los usuarios del panel, utiliza tokens Bearer JWT:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."
```

<Note>
  También puedes pasar una clave de API mediante `Authorization: Bearer
    dv_live_pk_...` (cualquier clave `dv_` — `dv_live_sk_`, `dv_test_sk_`,
  `dv_live_pk_`, `dv_test_pk_`) en entornos donde el encabezado personalizado
  `X-API-Key` está bloqueado por CORS. El servidor acepta ambas formas: lee
  primero `X-API-Key` y luego recurre a un token `Bearer` que lleva un prefijo
  `dv_`. Un JWT (que comienza con `eyJ`) sigue tratándose como un token de sesión
  del panel, de modo que ambos nunca entran en conflicto.
</Note>

## Formato de las claves de API

| Tipo                  | Prefijo       | Uso                                                 |
| --------------------- | ------------- | --------------------------------------------------- |
| Secreta de producción | `dv_live_sk_` | Llamadas API del lado del servidor                  |
| Secreta de prueba     | `dv_test_sk_` | Llamadas API del lado del servidor (modo de prueba) |
| Pública de producción | `dv_live_pk_` | Lado del cliente (SDK de navegador)                 |
| Pública de prueba     | `dv_test_pk_` | Lado del cliente (modo de prueba)                   |

<Warning>
  Una clave pública (`dv_live_pk_` / `dv_test_pk_`) está pensada para integrarse
  en código del lado del cliente, por lo que está **restringida a alcances de solo
  lectura** al crearse. Los alcances de escritura y administrativos —
  `messages:write`, `contacts:write`, `admin`, el comodín `*` y las lecturas
  sensibles de la cuenta `billing:read` / `settings:read` — se rechazan para una
  clave pública con un `422`. Usa una **clave secreta** (`dv_live_sk_`) para
  cualquier operación que envíe o modifique datos.

  Aun así, trata cualquier clave que envíes a un navegador o a un paquete móvil
  como visible públicamente y limítala a las lecturas mínimas que necesite.
</Warning>

## Inicio de sesión único (SAML)

Las organizaciones empresariales pueden iniciar sesión de los usuarios del panel
a través de un proveedor de identidad SAML 2.0 — Okta, Microsoft Entra ID
(anteriormente Azure AD), OneLogin, Google Workspace o PingFederate. El SSO
autentica a las personas en el panel; no genera claves de API, por lo que las
llamadas de servidor a servidor siguen usando los métodos anteriores.

Un propietario configura la conexión en **Configuración → Inicio de sesión
único** dentro del panel (o mediante `PATCH /api/v1/settings/saml`): define la
URL de SSO, el ID de entidad y el certificado de firma de tu IdP y, a
continuación, usa **Probar conexión** antes de activarla.

Cada organización obtiene su propio conjunto de endpoints, identificados por el
slug de tu organización (`orgSlug`). Se encuentran en la raíz de la API, **no**
bajo `/api/v1`:

| Método | Endpoint                        | Propósito                                                                  |
| ------ | ------------------------------- | -------------------------------------------------------------------------- |
| GET    | `/auth/saml/{orgSlug}/metadata` | XML de metadatos del proveedor de servicios para importar en tu IdP        |
| GET    | `/auth/saml/{orgSlug}/login`    | Iniciar el flujo de SSO (redirige a tu IdP)                                |
| POST   | `/auth/saml/{orgSlug}/callback` | Assertion Consumer Service (ACS): tu IdP publica aquí la respuesta firmada |
| GET    | `/auth/saml/{orgSlug}/logout`   | Iniciar el cierre de sesión único                                          |

Apunta tu IdP al endpoint de metadatos, por ejemplo
`https://api.orbit.devotel.io/auth/saml/acme/metadata` para la organización
`acme`.

## Aprovisionamiento de directorio (SCIM)

Aprovisiona y desaprovisiona usuarios del panel automáticamente desde tu
proveedor de identidad a través de SCIM 2.0. Genera un token de
aprovisionamiento en **Configuración → SCIM** (o mediante
`POST /api/v1/settings/scim/generate-token`): el token se muestra solo una vez,
así que cópialo en tu IdP de inmediato.

Tu IdP envía el token como una credencial Bearer en cada solicitud:

```bash theme={null}
curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"
```

Los endpoints siguen la especificación SCIM 2.0 y devuelven
`application/scim+json`. Se identifican por el slug de tu organización y se
encuentran en la raíz de la API, **no** bajo `/api/v1`:

| Recurso   | Endpoints                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| Users     | `/scim/v2/{orgSlug}/Users` (listar, crear), `/scim/v2/{orgSlug}/Users/{id}` (obtener, reemplazar, modificar, eliminar) |
| Groups    | `/scim/v2/{orgSlug}/Groups` (listar, crear/actualizar), `/scim/v2/{orgSlug}/Groups/{id}` (obtener)                     |
| Detección | `/scim/v2/{orgSlug}/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`                                               |

<Note>
  SAML y SCIM son independientes: el SSO controla cómo inician sesión los
  usuarios, SCIM controla qué usuarios existen. Puedes activar cualquiera de ellos
  por separado, aunque la mayoría de los IdP configuran ambos juntos.
</Note>

Para la guía completa de aprovisionamiento — construcción de la URL base,
asignación de roles, comprobaciones de estado del IdP y pasos para
Okta / Entra / cliente genérico — consulta la
[guía de aprovisionamiento SCIM 2.0](/compliance/scim-provisioning).