OAuth Apps - ImmiTranslate API

If you run a platform, such as a case management system, whose users each have their own ImmiTranslate account, create an OAuth app instead of asking every user for an API key. Your users connect their ImmiTranslate account to your platform, signing up first if they need to, and your platform receives an access token for that account. Create an app on the Developer Apps page to get a client ID and client secret, and register the redirect URIs your platform uses. An access token can do everything the person who connected it can do in their account.

The Developer Apps page, listing a verified app with its client ID and number of connections — Settings → Developers → Developer Apps

Creating an app. The name, logo and links appear on the screen where people approve the connection.

New apps are unverified: people outside your own account see a warning when connecting them, and they cannot pay for quotes. See Verification.

1. Send the user to ImmiTranslate

https://immitranslate.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&state=RANDOM_STATE

Parameter	Description
`client_id`	Your app’s client ID.
`redirect_uri`	One of the redirect URIs registered for your app, exactly as registered.
`response_type`	Always `code`.
`state`	A random value you check when the user comes back, to prevent cross-site request forgery.
`prompt`	Optional. `create` opens sign-up instead of log in, for users who don’t have an ImmiTranslate account yet. `consent` always shows the approval screen. `login` asks the user to log in again.
`login_hint`	Optional. The user’s email address, pre-filled on the log in or sign-up form.
`code_challenge`, `code_challenge_method`	Optional PKCE, with `S256`.

The user logs in or signs up, then approves the connection. If they have already connected your app, ImmiTranslate sends them straight back. An account can limit connecting apps to its admins; other users are told to ask an admin.

The approval screen: Connect EasyVisa to your ImmiTranslate account, with a Verified badge, what the app will be able to do, the signed-in account and Cancel and Connect buttons — The approval screen for a verified app

2. Receive the code

ImmiTranslate redirects to your redirect_uri with code and your state. If the user cancels, it redirects with error=access_denied instead.

3. Exchange the code for tokens

curl "https://api.immitranslate.com/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d redirect_uri=https://example.com/callback \
  -d code=CODE

{
  "token_type": "Bearer",
  "expires_in": 10368000,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200..."
}

Call the API with the access token exactly as you would with an API key: Authorization: Bearer ACCESS_TOKEN. Access tokens last 120 days. Before one expires, get a new pair with grant_type=refresh_token, your client ID and secret, and the refresh_token. Each refresh token works once and lasts 2 years. To find out who connected your app, call Get Account: user is the person the token acts for, and app says whether your app is verified and can pay.

4. Disconnect

curl "https://api.immitranslate.com/oauth/revoke" \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d token=ACCESS_OR_REFRESH_TOKEN

When a user disconnects ImmiTranslate from your platform, revoke their token (RFC 7009). Send either the access token or the refresh token, with your client ID and secret in the body or as HTTP Basic authentication; token_type_hint is optional. The connection is removed from the user’s ImmiTranslate account and every token your app holds for them stops working. The response is 200 with an empty body, even if the token was already revoked or unknown. A wrong client ID or secret returns 401 with invalid_client. People can also disconnect your app themselves, under Settings → Apps in their ImmiTranslate account. You receive a connection / revoked webhook when they do.

The Apps settings page, with the option to let only admins connect apps and a connected verified app showing who connected it and when it was last used — Settings → Apps in a connected account

Verification

New apps start unverified. Until your app is verified:

People outside your own account see a warning when they connect it.
It can’t pay for quotes. Pay Quote, and autobuy on Create Quote, return payment_requires_verified_app.

A verified app shows a Verified badge on the approval screen, can pay for quotes, and attributes the quotes it creates to your partner account automatically. To have your app verified, email developers@immitranslate.com. We’ll send you a questionnaire to complete and schedule a demo of the system.

Webhooks for apps

Set a webhook URL on your app on the Developer Apps page to receive webhook events for the quotes your app creates and the orders that follow, for every account connected to it, and for connections:

connection / created — a user connected your app. target is the account token; data has account (token and name), user (token and email) and connected_at.
connection / revoked — the account disconnected your app in ImmiTranslate, with the same data and revoked_at. Not sent when your app revoked the token itself.

Events stop for an account once it disconnects your app. App deliveries also carry a Webhook-App header with your app’s token and a Signature header: the hex HMAC-SHA256 of the raw request body, keyed with your app’s webhook signing secret (shown on the Developer Apps page). Compute it yourself and compare in constant time before trusting a delivery.

Errors

Code	Status	Meaning
`invalid_token`	401	The access token is invalid, expired or revoked. Refresh it, or ask the user to connect again.
`connection_revoked`	401	The account disconnected your app. Ask the user to connect again.
`account_changed`	401	The user who connected your app has moved to a different ImmiTranslate account. Ask them to connect again.
`app_suspended`	401	ImmiTranslate has suspended your app. Contact us.
`payment_requires_verified_app`	403	Only verified apps can pay for quotes (`Pay Quote`, or `autobuy` on `Create Quote`). From `Pay Quote`, the response includes `payment_url`: send the user there to pay for the quote on ImmiTranslate. A ready quote’s `payment_url` is also on the Quote Object.
`partner_mismatch`	403	A verified app sent a partner token for a different partner than its own.

​1. Send the user to ImmiTranslate

​2. Receive the code

​3. Exchange the code for tokens

​4. Disconnect

​Verification

​Webhooks for apps

​Errors

1. Send the user to ImmiTranslate

2. Receive the code

3. Exchange the code for tokens

4. Disconnect

Verification

Webhooks for apps

Errors