OAuth applications

Boxture uses OAuth2 to control which external applications may use the REST API and on whose behalf. Instead of handing out passwords, a Boxture user grants an application access once, and the application receives tokens it uses from then on. Access can be withdrawn at any time without changing anyone's password.

This page explains how a Boxture admin registers an application, how the authorization works for the user and the developer, and how to revoke access.

Concepts

Term	Meaning
Application	An external system that wants to use the API, for example a customer's ERP connector. It is registered in Boxture and gets an Application ID and a Secret.
Scopes	The areas of the API the application may use, such as orders or inventory:read. See Scopes.
Redirect URI	The address Boxture sends the user back to after authorizing, with an authorization code attached.
Authorization code	A short-lived code the application exchanges for tokens. It can be used once.
Access token	The key sent with every API request. Valid for one day.
Refresh token	Used to get a new access token when the old one expires, without the user signing in again.
Resource owner	The Boxture user who authorized the application. The API acts as this user and sees what this user sees.

Who can do what

The Admin › Integration › OAuth menu is only available to users with the Admin role. Admins register applications and can revoke them.

Any Boxture user can authorize an application when they are sent to the authorization page, but the application then only gets access to what that user can access. In practice you authorize with a dedicated integration user whose roles match what the integration must do.

OAuth applications

Go to Admin › Integration › OAuth › Applications. The list, Your applications, shows each application's Name, Uid (the application ID), Redirect uri, Scopes and whether it is Confidential. Click a row to open it.

Registering an application

1. Go to Admin › Integration › OAuth › Applications.

2. Choose Create in the card menu.

3. Fill in the Main tab:

   Field	What to enter
   Name	A name the user recognises; it is shown on the authorization page ("Authorize name to use your account?").
   Redirect uri	The address of the integration that receives the authorization code. Use one line per URI if there are several. For a server-side script without its own web page, use urn:ietf:wg:oauth:2.0:oob: Boxture then shows the code on screen so it can be copied.
   Confidential	Switch on when the application runs on a server and can keep the secret private. Switch off for apps that run on a phone or in a browser, where a secret cannot be kept safe.
   Scopes	The scopes the application may request, separated by spaces, for example orders inventory:read products:read shipments.

4. Click Submit.

After saving, the Details tab shows the Application ID and the Secret, each with a copy button. Give both to the developer through a secure channel.

WARNING

List every scope the integration needs on the application. A request for a scope that is not on the application is refused with "The requested scope is invalid, unknown, or malformed."

The tabs on an application

Tab	Content
Main	Name, redirect URI(s), confidential switch and scopes.
Details	Application ID and secret.
Call Back Urls	One entry per redirect URI, each with an Authorize button. Clicking it opens the authorization page for that URI with the application's scopes, which is the quickest way to get an authorization code yourself.
Authorized	The authorization codes issued for this application, with redirect URI, creation time and whether each is still Active or when it was revoked.

Changing or deleting an application

Open the application, change the fields and click Submit. Changing the scopes affects new authorizations; tokens that were already issued keep the scopes they were granted with until they expire.

Choose Destroy to delete the application. Boxture asks you to confirm: "You are about to permanently delete credentials that may be in use." All tokens of the application stop working immediately, so the integration stops.

Authorized applications

Admin › Integration › OAuth › Authorized (Your authorized applications) lists the applications with their Name, Scopes and Created at. Each row has a Revoke action. Revoking withdraws the access you granted that application: its tokens for your user stop working, and the application must be authorized again before it can use the API on your behalf.

Use this when an integration is retired, when a secret may have leaked, or when an integration should switch to a different user.

The authorization flow

This section is for the developer of the integration. Boxture supports the authorization code flow (with refresh tokens) and the implicit flow. Use the authorization code flow for server-side integrations.

1. Send the user to the authorization page

Open this address in a browser, with your application ID, redirect URI and the scopes you need (separated by %20):

https://oms.example.com/oauth/authorize?client_id=APPLICATION_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=orders%20inventory:read

The user signs in to Boxture if needed and sees Authorization required: "Authorize name to use your account?", followed by the list of what the application will be able to do. The user clicks Authorize (or Deny).

Boxture then redirects to your redirect URI with ?code=... attached. With urn:ietf:wg:oauth:2.0:oob, the Authorization code is shown on screen instead.

2. Exchange the code for tokens

POST /oauth/token
Content-Type: application/json

{
  "client_id": "APPLICATION_ID",
  "client_secret": "SECRET",
  "code": "AUTHORIZATION_CODE",
  "grant_type": "authorization_code",
  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob"
}

The response contains an access_token, a refresh_token, expires_in (in seconds, one day) and the granted scope. Store both tokens securely.

3. Call the API

GET /api/v1/inventories?limit=100
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

4. Refresh the access token

Before the access token expires (or when the API returns 401 with "The access token expired"), request a new one:

POST /oauth/token
Content-Type: application/json

{
  "client_id": "APPLICATION_ID",
  "client_secret": "SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "grant_type": "refresh_token",
  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob"
}

The response contains a new access token and a new refresh token. Use the new refresh token next time.

Troubleshooting

Message	Cause and fix
The requested scope is invalid, unknown, or malformed.	A requested scope is not listed on the application. Add it under Scopes or remove it from the request.
The requested redirect uri is malformed or doesn't match client redirect URI.	The redirect_uri in the request is not exactly one of the application's redirect URIs.
The provided authorization grant is invalid, expired, revoked, ...	The code was already used, has expired, or was issued for another redirect URI. Request a new code.
Client authentication failed due to unknown client, ...	Wrong application ID or secret, or the application was deleted.
The access token expired	Refresh the token (step 4).
The access token was revoked	Someone revoked the application. Authorize it again.

If the API answers "not found" for records you can see in Boxture, check which user authorized the token: the API only sees what that user sees. See What the API can and cannot see.