Skip to content
AI Inbx
Esc
↑↓navigate↵open⌘Jpreview

Create an OAuth app

Registers your own OAuth app so the mailbox consent screen carries your product’s name rather than AI Inbx. The response returns the redirect_uri to register with the provider, a hosted connect_url, and — for Google — the push_endpoint your own Pub/Sub topic should publish to. The slug is claimed globally because it forms the connect URL. return_urls lists the pages of yours a connect link (connect_url + /start?return_to=…) may send a person back to; without one, only the hosted page works.

POST/oauth-apps
Authorization
AuthorizationBearer token (API key) · headerrequired

Pass an AI Inbx API key as a Bearer token.

Header parameters
AIInbx-Workspacestring

Workspace id from GET /workspaces, for an OAuth token that reaches several.

min length 1
Request body
requiredapplication/json
providerstringrequired

google for Gmail, microsoft for Outlook.

Allowed:googlemicrosoft
namestringrequired

Your product's name, as the consent screen shows it.

min length 1 · max length 100
slugstringrequired

The connect URL's name. Unique across all of AI Inbx.

min length 3 · max length 64
client_idstringrequired

The OAuth client id, from Google Cloud or Microsoft Entra.

min length 1 · max length 500
client_secretstringrequired

The OAuth client secret that goes with the client id.

min length 1 · max length 2000
tenantstring

Microsoft only: the Entra tenant, for an app registered to one.

min length 1 · max length 128
pubsub_topicstring

Google only: your Pub/Sub topic, which Gmail publishes mailbox changes to.

min length 1 · max length 256
accentstring

The accent colour of your connect page.

max length 64
taglinestring

A line under your product's name on the connect page.

max length 200
support_emailstring<email>

Where people connecting a mailbox can reach you.

matches ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
logo_urlstring<uri>

Your logo, linked from your own server.

max length 2048
return_urlsstring<uri>[]

The pages a connect link may return to. Replaced whole on update.

max items 20
Responses
201

The OAuth app was created.

idstringrequired
matches ^[a-z]+_[0-9a-f]{32}$
providerstringrequired
Allowed:googlemicrosoft
namestringrequired
slugstringrequired
client_idstringrequired
tenantstring | nullrequired
Show properties
Any of:
string
string
null
null
pubsub_topicstring | nullrequired
Show properties
Any of:
string
string
null
null
accentstring | nullrequired
Show properties
Any of:
string
string
null
null
taglinestring | nullrequired
Show properties
Any of:
string
string
null
null
support_emailstring<email> | nullrequired
Show properties
Any of:
string<email>
string<email>
null
null
logo_urlstring<uri> | nullrequired

A logo linked from the customer's own server. An uploaded one is served from us and is not linkable through the API.

Show properties
Any of:
string<uri>
string<uri>
null
null
connect_urlstring<uri>required
return_urlsstring<uri>[]required

The pages a connect link — connect_url + /start?return_to=… — may return to. Matched on origin and path.

redirect_uristring<uri>required
push_endpointstring<uri> | nullrequired
Show properties
Any of:
string<uri>
string<uri>
null
null
created_atstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
400

The request is invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
401

The API key is missing or invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
402

The workspace has no plan (plan_required), or its plan's allowance is used up (allowance_reached).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
403

The API key or token does not have the required scope, or the token is connected as an inbox and the operation is not one an inbox may use.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
404

The requested resource does not exist.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
409

The request conflicts with the resource's current state.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
413

The request body or attachments are too large.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
415

The request body is not JSON.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
422

The request body failed validation.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
429

The organisation's request budget is spent (too_many_requests), or an upstream mail provider is throttling (rate_limited).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
500

An internal error occurred.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
502

An upstream mail provider failed.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
503

The service is temporarily unavailable.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
Request
import AIInbx from "aiinbx"

const aiinbx = new AIInbx()

const response = await aiinbx.oauthApps.create({
  provider: "microsoft",
  name: "Acme",
  slug: "acme",
  client_id: "00000000-0000-0000-0000-000000000000",
  client_secret: "client-secret-from-entra",
  return_urls: ["https://app.example.com/settings/email"],
})
Response
{
  "id": "string",
  "provider": "google",
  "name": "string",
  "slug": "string",
  "client_id": "string",
  "tenant": "string",
  "pubsub_topic": "string",
  "accent": "string",
  "tagline": "string",
  "support_email": "user@example.com",
  "logo_url": "http://example.com",
  "connect_url": "http://example.com",
  "return_urls": [
    "http://example.com"
  ],
  "redirect_uri": "http://example.com",
  "push_endpoint": "http://example.com",
  "created_at": "2019-08-24T14:15:22Z"
}