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.
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_KEYon every request;x-api-key: $AISA_API_KEYalso works. AIsa Connect accepts API keys only: an OAuth access token from MCP or CLI sign-in is rejected with401. 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
404with{"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.
Browse apps and actions
Reading the catalog is free.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’scredentialFields, 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_…) asapiKey, and the store’s myshopify.com domain asshopDomain, such asacme.myshopify.com. The Shopify admin URL of the same store is also accepted. - WooCommerce requires
storeUrl(the HTTPS store address),consumerKeyandconsumerSecret.wordpressUsernameandwordpressApplicationPasswordare optional; some WordPress endpoints need them. - Apps that take one key, such as OpenAI, need only
"apiKey": "...".
How credentials are checked
- AIsa checks the fields first, against the app’s
credentialFields. A missing required field, or a field the app does not take, returns400 invalid_request.paramnames the problem (apiKeyorcredentials), andmessagelists every field the app takes, for examplecredential shopDomain is required; the app takes apiKey, shopDomain (required). Nothing is sent to the app and nothing is created. - 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.
- Send
apiKeyonce: at the top level or incredentials, not both. Sending no credentials at all is also400 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 returns400 invalid_requestwithparam: "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)
Foroauth2 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 A failed session also has
state is completed, failed or expired:"error": {"code": "connect_denied", "message": "...", "isUserFixable": true}.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."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.
connectionIdis optional. Without it, AIsa uses the end user’s newestactiveconnection for the action’s app, and the response tells you which connection it used. - Input validation.
inputis checked against the action’sinputSchemabefore anything is sent. A mismatch returns422 validation_failed, withpathandmessagefor each problem inerror.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.
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-USDresponse 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
402and the action is not sent.
402 has a different body from the other errors:
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-service404 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 tohttps://api.aisa.one/apis/v1/connector.
Related
Billing & Credits
How your balance, top-ups and key spending limits work.
Authentication
Create, limit, store and rotate API keys.