---
title: "Generate external authentication links"
method: POST
path: "/api/v3/datasources/{datasource_name}/external-auth-links"
tags: ["Data source connections"]
---

# Generate external authentication links

`POST /api/v3/datasources/{datasource_name}/external-auth-links`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/datasources/{datasource_name}/external-auth-links`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `dts_session_id`
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/datasources/:datasource_name/external-auth-links/post.ts> (a function with typed inputs; its response is checked against the schema)

Generates one-time links that let an external user (for example, the end client of an agency)
authenticate a data source connection with their own credentials and select which accounts to
grant — without having access to the workspace. This is the API equivalent of the platform UI
action "Request credentials from another user".

One link is generated per email in `to_emails`; the email identifies the external user.
Links are single-use, expire after 14 days, and can be revoked.

**Who the link comes from.** An API token does not identify a person, so pass `requested_by`
with the email of the user the link is sent on behalf of. That user is shown as the sender on
the link page and in the invitation email, and receives the confirmation email once the
external user creates the connection. `requested_by` must be an active user of your agency
who is a member of the workspace or an owner of the agency; otherwise the request fails with
`400` and no links are created. Without `requested_by`, the link page and the invitation
show your whitelabel title, and no confirmation email is sent.

> **Important:** Requires the agency feature flag for external authentication links
> (contact Improvado to enable it). The endpoint returns `403` when the flag is disabled.

## Path parameters

- `datasource_name` string, required

## Request body

- ExternalAuthLinksCreateRequest
  - `to_emails` string[], required: Email addresses of the external users to generate links for. One link is generated per email; the email identifies the external user.
  - `send_email` boolean: When `true` (default), Improvado also emails the generated link to each recipient. Set to `false` to deliver the links yourself.
  - `requested_by` string, email: Email of the user the links are sent on behalf of. Must be an active user of your agency who is a member of the workspace or an owner of the agency; any other value is rejected with `400`. The user is shown as the sender on the link page and in the invitation email, and receives the confirmation email once the connection is created. The confirmation is skipped if the user has lost access to the workspace by then. When omitted, the link page and the invitation show your whitelabel title instead of a person, and no confirmation email is sent.

## Response `201`

External authentication links generated

- ExternalAuthLinksCreateResponse
  - `links` ExternalAuthLink[], required: Generated links, one per successfully processed email
    - `email` string, email, required: Email of the external user the link was generated for
    - `link` string, uri, required: One-time authentication link to share with the external user
    - `expires_at` string, date-time, required: Timestamp when the link expires (14 days after creation)
  - `failed_emails` string[], required: Emails for which link creation failed

## Other responses

- `400`: Validation error
- `401`: Forbidden
- `403`: External authentication links are not enabled for this agency. Contact Improvado to enable the feature.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)