Integration flow
This page walks you through embedding the fastn widget for your customers: register a customer organization, retrieve an embed token, and load the widget.
Terms used on this page are defined in the Glossary.
Pre-requisites
Before you start, you need an API key. We also recommend two optional security measures:
Enable caller identity verification (HMAC) on the API key.
Compute an identity hash on your backend and send it with every customer-specific request. The hash is recommended; it is required only when the key's identity verification is set to Enforce.
Creating an API key
Go to Embed → API keys and MCP → API keys (
/access).Click Create key. The Create an API key dialog opens.
In the dialog:
Name: give it something identifiable.
Mode: select Live for production use or Test for development. A live key also needs an Environment.
Set permissions (the Embed backend preset fits a backend that mints tokens), allowed IP addresses, rate limit and expiry as needed.
Enable caller identity verification (HMAC). This is optional but recommended for security.
Click Create key.
Creating an identity hash (recommended)
Sending an identity hash with customer-specific requests is optional, but we recommend it for security. The hash confirms that the org ID and user ID you're sending are ones your backend actually authorized.
If you skip this section, omit the x-identity-hmac header from your requests and don't enable HMAC on your API key.
1. Get your identity-verification secret
When you create an API key with HMAC enabled, a dialog appears showing the secret along with code snippets for generating the hash.

Safety precautions:
The secret is shown only once. If you lose it, you'll need to generate a new one.
Never ship the secret to the client. It must live only on your backend. If it appears in frontend code, anyone can forge a valid hash for any org or user.
2. Compute the hash
The hash is an HMAC-SHA256 of the org ID and user ID, joined with a newline and signed with your secret:
3. Send it with the identity headers
Attach the result as x-identity-hmac, alongside the plaintext x-org-id header and, if you use it, the optional x-user-id header:
The user ID is optional. If you don't send x-user-id, call identityHash(orgId) so the user ID defaults to an empty string.
The plaintext headers tell the gateway which identity is being claimed, and the hash proves that your backend authorized that specific claim. With the key set to Enforce, the gateway rejects any call whose hash is missing or doesn't match the one it recomputes from the plaintext values. With Monitor only, it logs mismatches and lets the call through.
Integration steps
Sign up a customer
1. Register the customer organization
Register the customer once from your backend with Create a Customer Organization, before you mint its first token. That endpoint needs an Admin key (full access), and the Embed backend key that mints tokens gets 403. Identity verification off is simplest. A key set to enforce needs identity headers on this call too. See API Reference: Create a Customer Organization.
Integrate the widget
2. Retrieve an embed token
From your backend server, call Generate Embed Token to get the authentication token for the customer. The token is in the response's data object: read it as data.token. See API Reference: Generate Embed Token.
3. Load the widget
Pass the token to your frontend and embed the iframe:
API Reference
Create a Customer Organization
Endpoint
Headers
Body
name is the only required field. plan is not needed: a paid plan here is refused with 403.
Register with an enforcing key
A key set to Enforce refuses a call with no identity headers (401 IDENTITY_HEADERS_REQUIRED), and this customer does not exist yet. Send x-user-id and leave out x-org-id. No end user exists yet, so use any stable id for your provisioning service. The hash signs an empty org id:
Do not send the new customer's id as x-org-id. It names a customer that must already exist, so the call returns 404 IDENTITY_ORG_NOT_FOUND.
Generate Embed Token
Endpoint
Headers
x-org-id is the customer: fastn's id for it, or the orgId you registered it under above.
Body
Send userId (or an attested x-user-id) so each person at the customer gets their own session; without one, every token gets a random user id. x-identity-hmac is required when the API key's identity verification is set to Enforce. The full field list is on Tokens, and every error, with a curl for each way of naming the customer, is in Generate embed tokens.
Response
Create a connection for a customer
Note: You only need this if you already hold the customer's credentials, such as a token for your own product. Otherwise the customer connects in the widget.
Endpoint
Headers
Body
connectorId
Yes
The connector. For your own product, GET /api/v1/saas-connectors lists it.
authMethodId
Yes
The auth method on that connector. GET /api/v1/auth-methods?connectorId=<CONNECTOR_ID> lists them.
credentials
Yes
The values for that auth method.
orgId
No
The customer, if you do not send x-org-id: your own id for it, or fastn's id for it. If you send both, they must match. With neither, the connection is created on your own organization, not a customer's.
name
No
A display name, unique per connector and customer. A name already in use returns 409. Leave it out and fastn generates one.
connectionScope is not accepted on this call and returns 400.
The field names in credentials come from the auth method. Each method lists them under inputContract.properties, so read them before you build this call. A method whose contract has a token field takes { "token": "..." }:
A complete call for one customer:
The call answers 201 with the new connection. It only creates: to replace a customer's credentials, such as when rotating a token, call PUT /api/v1/connections/{id} with the new credentials. Other answers:
400 IDENTITY_ORG_MISMATCH
orgId in the body names a different customer from x-org-id.
401 IDENTITY_HEADERS_REQUIRED or IDENTITY_HMAC_INVALID
The key is set to enforce, and the identity headers are missing or wrong.
403 Access denied
orgId in the body is not one of your customers.
403 CONNECTION_LIMIT_REACHED
This customer is at the connection limit you set for it.
403 quota_exceeded
Your customers already have as many connections as your plan includes.
403
The key lacks connections.create.
404 IDENTITY_ORG_NOT_FOUND
x-org-id is not one of your customers.
409
That name is already in use for this connector.
422
The app rejected these credentials, so nothing was saved. Check the field names and values.
504
fastn timed out while saving. The response says whether it is safe to try again.
With an Enforce key, every call needs identity headers, including the two lookups above. For the lookups, sign x-user-id with an empty org id, as in Register with an enforcing key. For this call, send and sign x-org-id as well and leave orgId out of the body, so the hash covers the customer.
Last updated
Was this helpful?

