Update Auth Configuration

Configure authentication for a custom integration

Using our API via a dedicated deployment? Just replace api.odeus.ai with your deployment's base URL: <deployment-url>/api/public

Configures the authentication method for an integration. This sets how users connect to the external service — via API key, OAuth, service account, or no authentication.

Changing the authType deletes all existing user connections to this integration. Users will need to reconnect.

Required Scopes

This endpoint requires the INTEGRATION_API scope.

Path Parameters

Parameter	Type	Required	Description
integrationId	string	Yes	UUID of the integration

Request Body

Parameter	Type	Required	Description
authType	string	Yes	Authentication method (see Auth Types below)
authFields	array	No	Fields users fill in when connecting (see Auth Field Schema)
authTestCode	string	No	JavaScript code to validate credentials (max 1,000 characters)
oauthClient	object	No	OAuth configuration (only for OAUTH / OAUTH_DCR auth types)

Auth Types

Type	Description
NONE	No authentication required
API_KEY	Users provide credentials via custom auth fields
OAUTH	OAuth 2.0 flow with authorization code
OAUTH_DCR	OAuth 2.0 with Dynamic Client Registration

Auth Field Schema

Each auth field defines a credential input that users fill in when connecting to the integration.

Property	Type	Required	Description
slug	string	Yes	Unique identifier for the field (max 100 characters)
label	string	Yes	Display label (max 100 characters)
type	string	Yes	Input type (see Field Types below)
description	string	No	Help text (max 500 characters, default: "")
placeholder	string	No	Placeholder text (max 200 characters)
required	boolean	No	Whether the field is required (default: false)

The slug must be unique within the integration. The field id is auto-generated — do not include it in the request.

Field Types

Type	Description
TEXT	Single-line text input
MULTI_LINE_TEXT	Multi-line text input
PASSWORD	Masked password input
NUMBER	Numeric input
EMBEDDING_MODEL	Embedding model selector

OAuth Client Schema

Only relevant when authType is OAUTH or OAUTH_DCR.

Property	Type	Required	Description
scopes	string	No	Space-separated OAuth scopes (max 2,000 characters)
authUrl	string	No	Authorization endpoint URL
tokenUrl	string	No	Token endpoint URL
clientId	string	No	OAuth client ID (max 500 characters)
clientSecret	string	No	OAuth client secret (max 500 characters, write-only)
label	string	No	Display label for the connect button (max 100 characters)
authorizationCode	string	No	Custom authorization code (max 1,000 characters)
accessTokenCode	string	No	Custom access token code (max 1,000 characters)
refreshTokenCode	string	No	Custom refresh token code (max 1,000 characters)

OAuth credentials (clientId, clientSecret, authUrl, tokenUrl) are write-only — they are never returned in API responses.

Example: API Key Authentication

const axios = require("axios");

async function configureAuth(integrationId) {
  const response = await axios.patch(
    `https://api.odeus.ai/integrations/v1/${integrationId}/auth`,
    {
      authType: "API_KEY",
      authFields: [
        {
          slug: "api_key",
          label: "API Key",
          type: "PASSWORD",
          description: "Your API key from the service dashboard",
          placeholder: "sk-...",
          required: true
        },
        {
          slug: "base_url",
          label: "Base URL",
          type: "TEXT",
          description: "API base URL",
          placeholder: "https://api.example.com",
          required: true
        }
      ],
      authTestCode: `
        const response = await fetch(secrets.base_url + '/me', {
          headers: { 'Authorization': 'Bearer ' + secrets.api_key }
        });
        if (!response.ok) throw new Error('Invalid credentials');
        return { success: true };
      `
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Auth configured:", response.data.integration);
}

configureAuth("550e8400-e29b-41d4-a716-446655440000");

Response Format

Success Response (200 OK)

{
  integration: {
    id: string;
    authType: string;
    authTestCode: string | null;
    authFields: Array<{
      slug: string;
      label: string;
      type: string;
      description: string;
      placeholder: string | null;
      required: boolean;
    }>;
    oauthClient: {
      scopes: string | null;
      label: string | null;
      authorizationCode: string;
      accessTokenCode: string;
      refreshTokenCode: string;
    } | null;
  };
}

Behavior

• Auth fields are fully replaced on every call — the entire array is deleted and recreated.
• Changing authType deletes all existing user connections and any previous OAuth client configuration.
• Setting authType to NONE, API_KEY, or SERVICE_ACCOUNT deletes any existing OAuth client.
• OAuth credentials (clientId, clientSecret) are encrypted before storage.

Error Handling

Status Code	Description
400	Invalid request body or integration ID
401	Invalid or missing API key
403	No access to this integration
404	Integration not found
429	Rate limit exceeded
500	Internal server error

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.