Docs
Sign in

OAuth applications

Register applications that act on behalf of UnitX users, understand the consent screen, and revoke access.

An OAuth application lets another piece of software act on behalf of a UnitX user — with their approval, in one organization, and only for the permissions it was registered for. The user never gives the application their password: they approve it on UnitX’s own consent screen.

When to use OAuth instead of an API key#

  • Use an OAuth application when the software should act as the person using it — for example a browser extension or a tool your colleagues each sign in to.
  • Use a service account and API key when the software runs on its own, such as a nightly sync.

Who can manage applications#

Permissions

oauth_application.viewoauth_application.createoauth_application.revoke
Applications are listed on the Applications tab of Governance, which needs oauth_application.view. Registering needs oauth_application.create and revoking needs oauth_application.revoke.

Register an application#

  1. Open Applications

    Go to GovernanceApplications.

  2. Name it

    Name, at least 2 characters. Users see this name when they approve it.

  3. Enter its redirect URLs

    Redirect URLs (comma-separated), for example https://example.com/callback. These are the only addresses UnitX will ever send an authorization code to, and they cannot be changed later.

  4. Choose its scopes

    Tick the permissions the application may use under Scopes. Scopes are permission keys, grouped by area. At least one is required.

  5. Choose Create application

    Copy the client secret now opens.

  6. Store the client secret

    This is the only time it is shown; UnitX keeps only a fingerprint of it. Copy it into the application’s secret store, then choose I’ve saved it. If it is lost, register a new application.

The application then appears in the list with its status, Client ID (not secret — the application presents it publicly), scopes, redirect URLs and creation date.

When someone starts using the application, it sends them to UnitX’s consent page. If they are not signed in, they sign in first as usual.

  • The page asks Allow <app> to use your UnitX account? and explains that it will act as them, in the organization currently selected in UnitX, and only for what is listed.
  • It will be able to lists each permission requested, or Nothing beyond identifying you.
  • Allow sends them back to the application. Deny shares nothing and shows Not authorized.
  • Approving never gives the application their password.

Note

If the consent page says This authorization link is incomplete, the application sent the person without its client ID or return address — start again from the application. Choose an organization in UnitX first means no organization is selected in UnitX yet.

Revoke an application#

  1. Choose Revoke

    On an active application in the list.

  2. Confirm

    Revoke <name>? warns that every access token the application has issued stops working immediately. Choose Revoke.

The application stays in the list as revoked with the date. This cannot be undone — register a new application if you need it again.

For developers: the authorization flow#

UnitX supports the OAuth 2.0 authorization code grant. There are no refresh tokens: when an access token expires, send the person through consent again.

Steps#

  1. Send the user to the UnitX consent page, /oauth/consent on the UnitX web address, with client_id, redirect_uri, scope (space-separated permission keys), state and, optionally, app_name (the name shown on the page) and code_challenge (PKCE, S256).
  2. When they choose Allow, UnitX redirects to your redirect_uri with code and your state. Check that state matches what you sent.
  3. Exchange the code within 5 minutes by posting JSON to /oauth/token on the UnitX API with grantType set to authorization_code, clientId, code, redirectUri and either clientSecret or, for a public client, codeVerifier. A code works once.
  4. Call the API with Authorization: Bearer <access token>. The token lasts one hour and is tied to the organization the user approved it in.
Redirect URI rules
The redirect URI must exactly match one registered for the application — no partial or pattern matches.
Scope rules
An application can only request scopes it was registered with. Asking for others fails with “This application is not registered for scope(s): …”.
Public clients
Software that cannot keep a secret, such as a browser extension, is registered as a public client with no client secret and must use PKCE. Public clients are registered through the UnitX API; the Applications form registers confidential clients.
“Invalid, expired, already-used, or redirect-mismatched code”

Codes last 5 minutes, work once, and must be exchanged with the same redirect URI used to obtain them. Start the flow again.

Can a user withdraw their own approval?

Revoking is done by an administrator on the Applications tab, and it stops the application for everyone at once.

What can an access token do?

Only what its approved scopes allow, in the one organization it was approved in. See API overview.

Still stuck? Search the docs with ⌘K, open Help inside UnitX, or contact support.