Custom Authentication

Custom Auth lets you obtain and automatically refresh an access token by calling your own HTTP endpoint. Use this when the target system requires a bespoke exchange instead of static bearer tokens or standard OAuth2 flows.

When to use

Use Custom Auth if:

• The provider exposes a proprietary token endpoint
• You must send dynamic query or body parameters
• The token and expiry are returned in a non‑standard JSON structure
• You cannot pre‑generate and manually rotate a long‑lived token

Avoid Custom Auth if a normal Bearer token or OAuth2 grant works. Simpler auth is easier to maintain.

Request configuration

You define a single HTTP request that the platform executes to fetch (and later refresh) a token.

Field	Description
Method	GET or POST. POST enables a request body section.
Authentication URL	Fully qualified URL to call for the token.
Query Parameters	Key/value pairs appended to the URL. Leave empty rows blank or remove them.
Request Body (POST only)	Key/value pairs sent in the body (application/x-www-form-urlencoded).
Token Key Name	JSON key in the response whose value is the access token.
Expiry Key Name	JSON key containing either an absolute timestamp or a duration.
Expiry Type	Interprets the expiry field: datetime, seconds, or milliseconds.

Response expectations

The endpoint must return JSON. Example (seconds):

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600
}

If expiry_type is datetime supply an ISO 8601 timestamp:

{
  "token": "abc123",
  "expire_at": "2025-09-14T12:34:56Z"
}

Configure Token Key Name = token, Expiry Key Name = expire_at, Expiry Type = datetime.

Expiry handling

We subtract a small safety window before actual expiration. If the field is a duration (seconds or milliseconds) a next refresh is scheduled relative to now. For datetime we parse the timestamp.

Security recommendations

• Use HTTPS only
• Scope the credentials to least privilege
• Do not log full responses (may contain secrets)
• Rotate underlying credentials periodically even if tokens auto‑refresh
• Validate TLS certificates

Example: POST with body

Request body parameters you add map to a form-encoded body:

Key	Value
client_id	my-client
client_secret	****
grant_type	custom_grant

Response:

{
  "access_token": "...",
  "expires_in": 900
}

Configure:

• Method: POST
• Token Key Name: access_token
• Expiry Key Name: expires_in
• Expiry Type: seconds

Limitations

• Only one custom auth request per connector
• Response must be valid JSON (no XML)
• No multi-step challenge flows

Troubleshooting

Symptom	Cause	Fix
400 Bad Request	Missing required parameter	Verify query/body keys match spec
401 / 403	Invalid credentials	Ensure secrets and scopes are correct
Token never refreshes	Wrong expiry key/type	Check expiry field name & type
JSON parse error	Non-JSON response	Ensure endpoint returns application/json

Next steps

After configuring Custom Auth, save the connector. Use the generated connector in project imports; the platform injects the token for subsequent upload requests automatically.