Auth guide

Sign up for free (no credit card):

In the dashboard, open the Integrations tab, click Configure New Integration, and pick the API.

curl --request GET \
  --url https://api.tenklo.dev/providers \
  --header 'Authorization: Bearer <NANGO-API-KEY>'

curl --request POST \
  --url https://api.tenklo.dev/integrations \
  --header 'Authorization: Bearer <NANGO-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "unique_key": "<INTEGRATION-ID>",
    "provider": "<PROVIDER>",
    "credentials": {
      "type": "OAUTH2",
      "client_id": "<CLIENT-ID>",
      "client_secret": "<CLIENT-SECRET>",
      "scopes": "<SCOPE-1>,<SCOPE-2>"
    }
  }'

In the Connections tab, click Add Test Connection, pick your integration, and authorize using a test account. The new connection's credentials appear in its Authorization tab — securely stored and automatically refreshed.

curl --request POST \
  --url https://api.tenklo.dev/connect/sessions \
  --header 'Authorization: Bearer <NANGO-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": {
      "end_user_id": "<TEST-USER-ID>"
    },
    "allowed_integrations": ["<INTEGRATION-ID>"]
  }'

For production OAuth apps, a callback URL on your own domain is recommended. Some providers show the callback domain to users.

To configure a custom callback URL:

1. Add an endpoint on your domain (e.g. https://example.com/oauth-callback) that 308-redirects to https://api.tenklo.dev/oauth/callback, preserving all query parameters.
2. Update the registered callback URL with each API provider — otherwise they'll reject new authorization flows.
3. After confirming steps 1 and 2, update the callback URL in Tenklo's Environment Settings. Settings are per-environment, so repeat for every environment.

Set up a backend endpoint that your frontend will call before each authorization attempt to retrieve a session token from Tenklo (API / Node SDK).

You'll need an API key with the environment:connect_sessions:write scope (find it in Environment Settings > API Keys).

import { Nango } from '@nangohq/node';

const nango = new Nango({ apiKey: process.env.NANGO_API_KEY! });

api.post('/sessionToken', async (req, res) => {
  const { data } = await nango.createConnectSession({
    tags: {
      end_user_id: '<END-USER-ID>',
      end_user_email: '<END-USER-EMAIL>',
      organization_id: '<ORGANIZATION-ID>'
    },
    allowed_integrations: ['<INTEGRATION-ID>']
  });

  res.status(200).send({ sessionToken: data.token });
});

allowed_integrations controls what the user sees:

• Multiple integrations — Connect UI shows a picker.
• Single integration — Connect UI sends the user straight to its auth flow.

Load the Tenklo frontend SDK, fetch the session token from your backend, and open Connect UI:

import Nango from '@nangohq/frontend';

const nango = new Nango();
const connect = nango.openConnectUI({
  onEvent: (event) => {
    if (event.type === 'close') {
      // Modal closed.
    } else if (event.type === 'connect') {
      // Auth flow successful.
    }
  },
});

const res = await fetch('/sessionToken', { method: 'POST' });
connect.setSessionToken(res.sessionToken); // A loading indicator shows until this is set.

See the Frontend SDK reference for more options.

The pre-built Connect UI is recommended but optional — if you need full UX control, follow Customize Connect UI. For email/cross-device flows, see Share a connect link.

When authorization succeeds, Tenklo generates a unique connection ID. You use this ID to manage the connection and retrieve its credentials. You must store it on your side, attached to the user/org/project that owns the connection — Tenklo doesn't model that ownership.

Set up the webhook in Environment Settings:

1. Specify a Webhook URL in the Tenklo UI.
2. Enable Send New Connection Creation Webhooks.
3. Handle POST requests on that route in your backend.

Webhook payload:

{
  "type": "auth",
  "operation": "creation",
  "success": true,
  "connectionId": "<CONNECTION-ID>",
  "tags": {
    "end_user_id": "<END-USER-ID>",
    "end_user_email": "<END-USER-EMAIL>",
    "organization_id": "<ORGANIZATION-ID>"
  }
}

Persist connectionId against whichever entity owns the connection in your app.

Credentials can become invalid when users revoke access, providers rotate refresh tokens, scopes change, or an app moves from testing to production. Re-authorization updates an existing connection's credentials while preserving its data and config. Deleting and re-creating the connection wipes that data — prefer re-authorization.

Before showing integration settings, check the connection with GET /connections/{connectionId}:

import { Nango } from '@nangohq/node';

const nango = new Nango({ apiKey: process.env.NANGO_API_KEY! });

try {
  await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');
  // Connection is valid.
} catch (error) {
  if (error.response?.data?.error?.code === 'invalid_credentials') {
    // Connection is invalid — show a Reconnect button.
    displayReconnectUI();
  }
}

An invalid_credentials error means the connection failed credential refresh or validation — show an error state with a Reconnect button.

To trigger re-authorization, use the same frontend flow as a new connection, but generate a reconnect session token on the backend. Pass the returned token to the Frontend SDK exactly like a normal session token. On success you'll receive an auth webhook with operation = override.

The connection keeps its connection ID. It also keeps its tags, unless the reconnect session passes non-empty tags or an end_user, which replace them.

import { Nango } from '@nangohq/node';

const nango = new Nango({ apiKey: process.env.NANGO_API_KEY! });

api.post('/sessionToken', async (req, res) => {
  const { data } = await nango.createReconnectSession({
    connection_id: '<CONNECTION-ID>',
    integration_id: '<INTEGRATION-ID>'
  });

  res.status(200).send({ sessionToken: data.token });
});

Test the auth flow from your app and verify a connection appears in the Connections tab. Failed attempts are inspectable in the Logs tab.

curl --request GET \
  --url 'https://api.tenklo.dev/connections?tags[end_user_id]=<END-USER-ID>' \
  --header 'Authorization: Bearer <NANGO-API-KEY>'

🎉 You are connected! Next:

• View connections and credentials in the Connections tab.
• Retrieve credentials via the API or Node SDK.
• Build with sync functions, Action functions, webhook functions, or any other Tenklo function type.