Skip to main content
AIsa Connect lets your end users, for example the merchants you serve, connect their own app accounts such as Shopify, WooCommerce, GitHub or Google to AIsa. With one AIsa API key you then browse the app catalog and run app actions for those users: read orders, update products, list repositories and so on. AIsa’s app integration holds the end users’ tokens and keys, so your system does not store them and cannot read them back. All AIsa accounts can use AIsa Connect with their existing API key and balance. No separate sign-up is needed.

When to use it

  • Your product acts inside apps that your users own, and you do not want to build and maintain an OAuth app or a credential vault for each one.
  • You want one catalog of apps and actions, each with a JSON Schema for its input, instead of one SDK per app.
  • You want to pay only for actions that succeed, from the same balance as your models and data APIs.
To read public data that needs no user account, such as marketplace listings, use the Data APIs instead. For one request shape across social and ad platforms, see Unified APIs.

Core concepts

How it works

1

Pick an app and an action

Search the catalog for the app, read its authTypes and credentialFields, and look up the action’s inputSchema. Browsing is free. See Browse apps and actions.
2

Connect the end user's account

For api_key and custom_credential apps, collect the fields in your UI and send them to AIsa. For oauth2 apps, send the user to the AIsa hosted page and poll the session. See Connect with credentials and Connect with OAuth.
3

Run actions

Call POST /actions/run with the action key, the externalUserId and an input that matches the schema. See Run actions.

Before you start

  • Authentication. Send Authorization: Bearer $AISA_API_KEY on every request; x-api-key: $AISA_API_KEY also works. AIsa Connect accepts API keys only: an OAuth access token from MCP or CLI sign-in is rejected with 401. See Authentication for creating, limiting and rotating keys.
  • Server side only. Call AIsa Connect from your backend. Never put the API key in a browser or mobile app.
  • Availability. If every AIsa Connect path returns 404 with {"error":"api endpoint not found"}, AIsa Connect is temporarily unavailable in that environment. Contact developer@aisa.one.

End user IDs

externalUserId is the ID of the end user in your system. AIsa uses it to keep your end users apart.
  • Format: 1–250 printable ASCII characters, with no leading or trailing spaces. Use a stable ID that contains no personal data, such as store_8812. Do not use an email address.
  • Where it is required: starting a connection and running an action. When listing connections it is an optional filter.
  • Isolation: a connection belongs to your AIsa account and one externalUserId. When user A runs an action, AIsa never uses user B’s connection.
GET /connections/{connectionId} and DELETE /connections/{connectionId} only check that the connection belongs to your AIsa account. They do not check the end user. Keep the mapping from connection to end user in your backend, and never let an end user pass in an arbitrary connection ID.

Browse apps and actions

Reading the catalog is free.
An action has key, app, name, description, operationType (read, write or destructive), requiredScopes, inputSchema and outputSchema. An app’s authTypes decides how it connects: credentialFields lists the credential fields for each credential auth type. Each field has key (the name to send), label (usable as a form label), required, and secret (render it as a password input). For api_key, the first field is always apiKey. If an auth type is missing from credentialFields, AIsa does not know its fields and the app checks whatever you submit. An app that only supports OAuth has credentialFields: {}.

Connect with credentials

Most commerce apps, including Shopify and WooCommerce, connect with credentials. Ask the end user for the fields listed in the app’s credentialFields, then forward them to AIsa in credentials. apiKey can also be sent at the top level; it is the same as credentials.apiKey.
  • Shopify takes the store’s Admin API access token (shpat_…) as apiKey, and the store’s myshopify.com domain as shopDomain, such as acme.myshopify.com. The Shopify admin URL of the same store is also accepted.
  • WooCommerce requires storeUrl (the HTTPS store address), consumerKey and consumerSecret. wordpressUsername and wordpressApplicationPassword are optional; some WordPress endpoints need them.
  • Apps that take one key, such as OpenAI, need only "apiKey": "...".
A successful connect returns the new connection:

How credentials are checked

  1. AIsa checks the fields first, against the app’s credentialFields. A missing required field, or a field the app does not take, returns 400 invalid_request. param names the problem (apiKey or credentials), and message lists every field the app takes, for example credential shopDomain is required; the app takes apiKey, shopDomain (required). Nothing is sent to the app and nothing is created.
  2. The app then checks the credentials themselves. A wrong token, a shop domain that is not a myshopify.com domain, or a WooCommerce address that is not HTTPS returns 400 connect_failed. Ask the user to check what they entered.
Other rules:
  • Send apiKey once: at the top level or in credentials, not both. Sending no credentials at all is also 400 invalid_request.
  • Unknown fields in the request body are rejected with 400 invalid_request.
  • An app that is not in the catalog returns 404 not_found. An app that only supports OAuth returns 400 invalid_request with param: "app"; use the hosted page instead.
  • AIsa does not store, log or return the credentials you send, and error messages never contain credential values.

Connect with OAuth (hosted page)

For oauth2 apps, AIsa hosts the authorization page. Start a connect session for the end user:
1

Open the complete connectUrl

Open the complete connectUrl in the end user’s browser. The part after # is the session secret: do not cut it off, and do not write it to logs. The session expires after 30 minutes.
2

The user authorizes the app

When the flow ends, the browser goes to redirectUrl with ?connectSessionId=cs_...&connectionId=con_..., plus &error=<code> on failure. redirectUrl must be HTTPS and on your account’s redirect allowlist. To add a URL prefix to the allowlist, send it to developer@aisa.one. Without redirectUrl, the user stays on AIsa’s result page.
3

Poll the session from your server

The session is the source of truth. Poll it every 2–3 seconds until state is completed, failed or expired:
A failed session also has "error": {"code": "connect_denied", "message": "...", "isUserFixable": true}.
Session states are created, authorizing, completed, failed and expired. AIsa creates the connection only after it confirms with the app that authorization finished. The parameters on the redirect are not trusted on their own, so you do not need to forward them to AIsa. If the user returns before the app has recorded the authorization, the hosted page checks again for about 10 seconds; if the user comes back without finishing, the page sends them back to the app’s authorization screen. Reauthorize a connection. When a connection needs reconnecting, start a session again with connectionId=con_.... The existing connection is updated in place.

Manage connections

Listing, reading and deleting connections is free.
Deleting returns the connection with "status": "disconnected". After that, reading it returns 404 not_found. By default an AIsa account can have 100 active connections, counted across all of your end users. Beyond that, connecting returns 403 user_quota_exceeded. Delete connections you no longer use, or contact us to raise the limit.

Run actions

  • Which connection. connectionId is optional. Without it, AIsa uses the end user’s newest active connection for the action’s app, and the response tells you which connection it used.
  • Input validation. input is checked against the action’s inputSchema before anything is sent. A mismatch returns 422 validation_failed, with path and message for each problem in error.details.errors. Fields the schema does not declare are rejected.
  • No automatic retries. Each run is sent to the app once. AIsa never retries it for you.
  • Run ID. Errors that happen after the run was sent carry error.details.runId. Include it when you contact us.
Treat write and destructive actions with care. Check operationType before you run an action, and confirm with the end user when the action changes their data. If a write returns app_error or outcome_unknown, the change may already have happened: check the result in the app before you decide to retry, so you do not write twice.

Billing

  • Only successful runs are charged, at USD 0.0003 per run (300 micro-USD). The price is the same on every plan; no plan multiplier applies.
  • Failed runs are never charged. That includes validation failures, missing connections, connections that need reconnecting, rate limiting, app errors and unknown outcomes.
  • Browsing the catalog, connecting, and reading or deleting connections are free.
  • Each run reports what it cost in the X-AISA-Customer-Cost-Micros-USD response header, in micro-USD (1 USD = 1,000,000 micro-USD).
  • Before a run is sent, AIsa reserves the cost of one run. If the balance is too low, the request fails with 402 and the action is not sent.
A 402 has a different body from the other errors:
If the API key has a spending limit and that limit is used up, code is insufficient_api_key_balance. Top up or adjust the key’s limit as described in Billing & Credits.

Rate limits

Limits apply per API key: Over the limit, AIsa returns 429 rate_limited with a Retry-After header. An app can also rate limit a request; then the error has attribution: "upstream", and the app’s wait time, when it gives one, is passed on in Retry-After and in error.details.retryAfterSeconds. Rate-limited requests are not charged.

Errors

Apart from the unavailable-service 404 and the 402 above, every error has this shape:
attribution says where the problem is: user (the request or the end user’s connection), upstream (the app) or aisa (AIsa). Handle errors by code, not by the text of message. When you contact developer@aisa.one, include the approximate UTC time, the method and path, the status, the error code, and the runId when there is one. Never include API keys, end user credentials or the connectUrl secret.

API reference

Paths are relative to https://api.aisa.one/apis/v1/connector.

Billing & Credits

How your balance, top-ups and key spending limits work.

Authentication

Create, limit, store and rotate API keys.