Skip to main content
SpireSlip

Connecting third-party apps via OAuth

OAuth is how external apps connect to your SpireSlip data when you're not the developer. If a partner company builds a payroll-analytics dashboard, a CFO console, or a tax-filing add-on, they use OAuth instead of asking for an API key: you stay in control of which apps are connected, what they can see, and you can revoke their access in one click.

OAuth or API keys?

Pick the right tool for the job:

  • API keys: for connecting your SpireSlip account to TaxSpire, Wovendesk, a custom script, or any first-party integration you own end-to-end. You hold the key; you're responsible for its security.
  • OAuth: for third-party apps where the developer is someone else. Users see a consent screen, the access token is bound to one entity, refresh tokens rotate on use, you can revoke the app and instantly invalidate every token it holds. Standard OAuth 2.0 with PKCE, the same protocol used by GitHub, Google, and Stripe.

Plans with OAuth access

OAuth is included on the Complete, Enterprise, and Accountant plans: the same plans as API keys. Core and Plus accounts see a locked card with an upgrade prompt where the OAuth section would otherwise be. The same plan gate also blocks token validation at runtime, so an OAuth app that was authorised before a downgrade stops working as soon as the plan changes.

Registering an OAuth application

The developer of the third-party app needs a client_id and a client_secret from you. Generate those in SpireSlip:

  1. Open Settings → OAuth applications (or jump in via Entities → Integrations → the OAuth applications card).
  2. Click Register a new application.
  3. Enter the application's name (will appear on the consent screen).
  4. Enter the redirect URI the developer gave you. Must be HTTPS in production; http://localhost is allowed during development. This is the URL OAuth sends users back to after they approve.
  5. Tick the scopes the application has asked for. Tighter is better: do not grant payroll:approve to a read-only analytics app.
  6. Click Register application.

The client_id and client_secret are shown once on the next screen. Copy both and pass them to the developer through a secure channel (a password manager, an encrypted file transfer, never plain email). SpireSlip never sees the client_secret again; the developer never sees the resource owner's password.

What happens when a user authorises an app

From the user's perspective:

  1. The third-party app sends them to SpireSlip's consent screen via a link or popup. SpireSlip checks they're signed in (prompting if not).
  2. The consent screen shows the application name, the scopes being requested in plain English, and a dropdown of the user's entities.
  3. The user picks an entity. The access token will only see data from that entity: even if the user has access to a dozen, the third-party only ever sees the one they picked.
  4. The user clicks Authorise. SpireSlip redirects back to the app with a one-time authorisation code.
  5. The app's backend exchanges the code for an access token (1 hour lifetime) and a refresh token (30 days lifetime). From then on, the app uses the access token to call /api/v1/* endpoints just like any API key holder.

Available scopes

The OAuth scope vocabulary is identical to the API key permission list: same six strings, same meanings:

  • paye:read / pension:read: PAYE and pension schedules.
  • payroll:read: payroll runs and lines (sensitive fields masked).
  • payroll:approve, two-step approval flow. Only an owner or admin can allow an application this scope, and it works only while that person is still an active owner or admin: if their role is changed or they are deactivated, the application's approvals are refused with approver_role_required.
  • employees:read: masked employee directory.
  • reports:read: reserved for future use.

You decide which scopes the application can ever request at registration; if a developer asks for a scope you didn't enable, the authorise step fails before any user sees the consent screen.

Token lifetime and refresh

Access tokens expire 1 hour after issuance. Apps use the long-lived refresh token (30 days) to mint a new access token without prompting the user. Refresh tokens rotate on each use: SpireSlip invalidates the old refresh token and issues a fresh one with the new access token. This means a stolen refresh token only buys an attacker one extension window; the next legitimate use by the app revokes the stolen copy automatically.

The entity binding chosen at consent travels with refresh-token rotation. If a user authorised for Entity A, every refreshed access token over the next 30 days still only sees Entity A.

Revoking an application

Open Settings → OAuth applications, find the application row, click Revoke. The revoke action does three things atomically:

  • Marks the OAuth client revoked: no new tokens can be issued.
  • Revokes every access token ever issued to the client: in-flight callers stop being authorised on their next request.
  • Revokes the matching refresh tokens: the app cannot mint replacement access tokens.

A revoked application can never be reinstated: if the developer needs access again, register a new application from scratch. The audit log records the revoke event for the entity history view.

For integration developers

If you're building the third-party app rather than authorising one, here's what you need to know:

  • SpireSlip runs OAuth 2.0 Authorization Code grant with PKCE. Client Credentials and Password grants are disabled: every access token must come from a user-approved authorise step.
  • Authorisation endpoint: /oauth/authorize. Token endpoint: /oauth/token. Both are auto-registered by Laravel Passport.
  • Pass code_challenge + code_challenge_method=S256 at /authorize, and the matching code_verifier at /token. SpireSlip rejects flows without PKCE for confidential and public clients alike.
  • Every /api/v1 request must include ?entity_id=N matching the entity bound at consent. Mismatch returns 403 entity_mismatch.
  • Don't log access tokens or refresh tokens. Don't expose either in client-side code (browser, mobile UI). Use a backend-only secret store.

Questions about a specific app? The application owner can reach SpireSlip support at hello@spirecoretech.com.