Update Auth Configuration
Configure authentication for a custom integration
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.
Before You Start
- Changing
authType: Changing theauthTypedeletes all existing user connections to this integration. Users will need to reconnect.
Base URL
https://api.ajan.io/integrations/v1/{integrationId}/authRequired Scopes
This endpoint requires the INTEGRATION_API scope.
Parameters
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) |
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) |
Example: API Key Authentication
javascript
const axios = require("axios");
async function configureAuth(integrationId) {
const response = await axios.patch(
`https://api.ajan.io/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 ld.request({
method: "GET",
url: data.auth.base_url + "/me",
headers: { Authorization: "Bearer " + data.auth.api_key }
});
if (response.status < 200 || response.status >= 300) {
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)
typescript
{
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
authTypedeletes all existing user connections and any previous OAuth client configuration. - Setting
authTypetoNONE,API_KEY, orSERVICE_ACCOUNTdeletes 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 |