Skip to content

Commit

Permalink
docs: authorize and reconnect (#3151)
Browse files Browse the repository at this point in the history 
## Changes

- Document how to reconnect
  • Loading branch information
@bodinsamuel
bodinsamuel authored Dec 11, 2024
1 parent d21277c commit 9719e85
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 10 deletions.
60 changes: 54 additions & 6 deletions docs-v2/guides/getting-started/authorize-an-api-from-your-app.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,20 +86,20 @@ api.post('/sessionToken', (req, res) => {

In some cases, a connection belongs to an organization rather than a user. In such cases, fill in the relevant organization information, in additional to the required end user information (based on the user who initiated the authorization flow). Sometimes, the user email in your app will not match the email they use to connect their external account, which is fine. If you really cannot provide a user ID and email, you can use placeholders without affecting how Nango operates.
</Info>

</Accordion>

## Trigger the auth flow (frontend)

In **your frontend**, load the Nango frontend SDK, retrieve the session token from the backend, and trigger the authorization flow.
In **your frontend**, load the Nango frontend SDK, retrieve the session token from the backend, and trigger the authorization flow.

### Option 1: Use the Nango Connect UI

```js
import Nango from '@nangohq/frontend';

const nango = new Nango();
const connect = nango.openConnectUI({
const connect = nango.openConnectUI({
onEvent: (event) => {
if (event.type === 'close') {
// Handle modal closed.
Expand All @@ -119,7 +119,7 @@ Refer to the [_Authorize an API from your app with custom UI_ guide](/guides/aut

## Save the Connection ID (backend)

The connection ID, a UUID generated by Nango, is required to manage the connection and access its credentials & data. So you need to persist this ID.
The connection ID, a UUID generated by Nango, is required to manage the connection and access its credentials & data. So you need to persist this ID.

Upon successful authorization, Nango will send a webhook to your backend with the connection ID.

Expand All @@ -141,15 +141,63 @@ Successful authorization webhooks sent by Nango are `POST` requests with the fol
}
```

For each successful authorization, persist the `connectionId` value alongside its corresponding user or organization, designated by `endUser.endUserId` and `endUser.organizationId`.
For each successful authorization, persist the `connectionId` value alongside its corresponding user or organization, designated by `endUser.endUserId` and `endUser.organizationId`.

# Troubleshoot authorization errors

If an authorization request fails, you can analyze the relevant log in the _Logs_ tab of the Nango UI.

# Reconnect an existing connection

When testing or troubleshooting an issue, you may need a user to re-authorize an API. Nango allows you to do this without deleting and recreating the connection. Instead, you can reconnect an existing connection while preserving its metadata and configuration.

In **your backend**, use the `POST /connect/sessions/reconnect` endpoint ([API](/reference/api/connect/sessions/reconnect)/[SDK](/reference/sdks/node#create-a-reconnect-session) reference) to generate a session token specifically for reconnecting a user. This token is then used on the frontend in the same way as when creating a connection, but it will reconnect the existing connection instead.

<Tabs>

<Tab title="cURL">

```bash
curl --request POST \
--url https://api.nango.dev/connect/sessions/reconnect \
--header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
--header 'Content-Type: application/json' \
--data '{
"connection_id": "<CONNECTION-ID>",
"integration_id": "<INTEGRATION-ID>"
}'

```

</Tab>

<Tab title="Node">

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

const nango = new Nango({ secretKey: process.env['<NANGO-SECRET-KEY>'] });

api.post('/sessionToken', (req, res) => {
// Ask Nango for a secure token to reconnect
const res = await nango.createReconnectSession({
connection_id: "<CONNECTION-ID>",
integration_id: '<INTEGRATION-ID>',
});

// Send this token back to your frontend
res.status(200).send({
sessionToken: res.data.token
});
});
```
</Tab>

</Tabs>

# You are ready

You have successfully set up the authorization flow for your users. Next steps:
You have successfully set up the authorization flow for your users. Next steps:
- View new connections & associated credentials in the _Connections_ tab of the Nango UI
- Retrieve connection credentials with the [API](/reference/api/connection/get) or [Node SDK](/reference/sdks/node#get-a-connection-with-credentials)
- [Read data](/guides/getting-started/read-from-an-api) from the API
Expand Down
16 changes: 12 additions & 4 deletions docs-v2/spec.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -254,9 +254,11 @@ paths:
created_at:
type: string
description: The creation timestamp of the sync.
format: date-time
updated_at:
type: string
description: The last updated timestamp of the sync.
format: date-time
syncs:
type: array
items:
Expand All @@ -268,9 +270,11 @@ paths:
created_at:
type: string
description: The creation timestamp of the sync.
format: date-time
updated_at:
type: string
description: The last updated timestamp of the sync.
format: date-time
description:
type: string
description: Description of what the sync does and details about it
Expand Down Expand Up @@ -459,7 +463,7 @@ paths:
description: |
List of connection errors. Ex:
- Connection credentials are invalid (type=auth)
- Last sync for the connnection has failed (type=sync)
- Last sync for the connection has failed (type=sync)
post:
description: Adds a connection for which you already have credentials.
Expand Down Expand Up @@ -1022,6 +1026,7 @@ paths:
required: false
schema:
type: string
format: date-time
description: A timestamp (e.g., 2023-05-31T11:46:13.390Z) used to fetch records modified after this date and time. If not provided, all records are returned. The modified_after parameter is less precise than cursor, as multiple records may share the same modification timestamp.
- name: delta
in: query
Expand Down Expand Up @@ -1067,6 +1072,7 @@ paths:
type: string
nullable: true
description: The timestamp at which Nango detected the record as deleted
format: date-time
last_action:
type: string
description: The last action seen on this record
Expand All @@ -1075,10 +1081,12 @@ paths:
type: string
description: The timestamp at which Nango first saw this record
example: '2023-09-18T15:20:35.941305+00:00'
format: date-time
last_modified_at:
type: string
description: The timestamp at which Nango last detected a change to this record
example: '2023-09-18T15:20:35.941305+00:00'
format: date-time
cursor:
type: string
description: The current cursor of the record. Use this to fetch records updated after this record
Expand Down Expand Up @@ -2088,11 +2096,11 @@ components:
description: Absolute path to the logo of this integration (svg)
created_at:
type: string
format: date
format: date-time
description: When it was created
updated_at:
type: string
format: date
format: date-time
description: Last time it was updated
IntegrationFull:
allOf:
Expand Down Expand Up @@ -2217,4 +2225,4 @@ components:
expires_at:
type: string
description: When the token expires
format: date
format: date-time

0 comments on commit 9719e85

Please sign in to comment.