DocsApps

OAuth apps

An app that acts for other people, such as an internal tool or a browser extension, signs them in with OAuth 2.1 instead of asking for an API key. Each person approves your app, and can revoke it whenever they like.

Grant
Authorization code + PKCE (S256)
Auth header
Authorization: Bearer ssat_…
Full reference
API reference: OAuth
On this page
  1. OAuth or an API key
  2. Registering an app
  3. Endpoints
  4. Signing someone in
  5. Tokens and refresh
  6. Scopes and roles
  7. Errors and limits
  8. Checklist

OAuth or an API key

An API key acts as the person who created it. That suits a script or a CI job. When your app acts for whoever is using it, use OAuth: each person signs in to ShareShield themselves, chooses the organisation, and approves the scopes. Your app never sees their password and never holds a long-lived key.

OAuth tokens work with /api/v2. /api/v1 accepts only API keys. OAuth apps are available on every plan.

Registering an app

Owners and admins register apps under Dashboard → OAuth apps. Only members of the organisation that registered an app can authorise it, and its tokens reach only that organisation. Choose the kind of client:

  • Confidential, for an app with a server that can keep a secret. It authenticates with its client secret (client_secret_basic or client_secret_post). The secret is shown once and can be rotated.
  • Public, for browser extensions and single-page, desktop and mobile apps. It sends only its client_id.

Redirect URIs are matched exactly, and you send redirect_uri on every request. They can be https:// URLs, loopback addresses (http://127.0.0.1 or http://[::1], on any port), or, for public clients, chrome-extension:// and moz-extension:// URLs.

From the same page you can disable an app, which ends every token at once, see which members have authorised it with which scopes, and revoke them. Members see the apps they’ve approved under Profile → Authorized apps.

Endpoints

Paths are relative to https://app.shareshield.net. Read them from the metadata document rather than hard-coding them, so your app keeps working if they move.

PurposeMethod and path
Server metadata (RFC 8414)GET /.well-known/oauth-authorization-server
Authorization, in the browserGET /oauth/authorize
Token (form-encoded)POST /api/oauth/token
Revocation (RFC 7009)POST /api/oauth/revoke
Introspection (RFC 7662), confidential clients onlyPOST /api/oauth/introspect

Signing someone in

ShareShield supports only the authorization code grant, with PKCE using S256, and PKCE is required for every client. There is no implicit, password or client-credentials grant.

1. Send them to the authorization endpoint

Make a fresh random verifier and state for every sign-in:

Terminalbash
# PKCE: a random verifier and its S256 challenge
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

open "https://app.shareshield.net/oauth/authorize?response_type=code\
&client_id=$CLIENT_ID\
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback\
&scope=secrets%3Acreate%20secrets%3Alist\
&state=$STATE\
&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

ShareShield signs the person in if needed, with their password, two-factor code or single sign-on, and shows the consent screen. They choose the organisation and can untick scopes; scopes their role doesn’t allow can’t be granted. Then ShareShield redirects to redirect_uri with code, state and iss, or with error (for example access_denied). Check that state matches what you sent and that iss equals the issuer in the metadata. Problems with the client or the redirect URI are shown to the person and never redirected.

2. Exchange the code

Within two minutes, and only once:

Terminalbash
curl -sS "https://app.shareshield.net/api/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code -d code="$CODE" \
  -d redirect_uri=https://app.example.com/callback -d code_verifier="$CODE_VERIFIER"
# Public clients: drop -u and add -d client_id="$CLIENT_ID"

{ "access_token": "ssat_…", "token_type": "Bearer", "expires_in": 3600,
  "refresh_token": "ssrt_…", "scope": "secrets:create secrets:list" }

The granted scope can be narrower than you asked for. Read it, and turn off the features it doesn’t cover.

3. Call the API

Terminalbash
curl -sS "https://app.shareshield.net/api/v2/me" -H "Authorization: Bearer $ACCESS_TOKEN"
# → { …, "via": "oauth", "oauthApp": { "clientId": "…", "name": "…", "scopes": [ … ] }, "scopes": [ … ] }

Send the token as Authorization: Bearer and no other credential. The audit log records the person as the actor and your app alongside.

Tokens and refresh

TokenPrefixLifetime
Authorization codessac_2 minutes, single use
Access tokenssat_1 hour
Refresh tokenssrt_30 days from its last use, replaced on every refresh
Client secretsscs_Until rotated. Confidential clients only
Terminalbash
curl -sS "https://app.shareshield.net/api/oauth/token" -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN"
# Returns a NEW refresh token. Store it and discard the old one.

# Sign out: revoking the refresh token ends the whole sign-in
curl -sS "https://app.shareshield.net/api/oauth/revoke" -u "$CLIENT_ID:$CLIENT_SECRET" -d token="$REFRESH_TOKEN"

Revocation always answers 200. Delete your stored tokens whatever it returns. ShareShield stores tokens, codes and client secrets only as hashes.

Scopes and roles

OAuth uses the same scopes as API keys, space-separated: secrets:create, secrets:read, secrets:burn, secrets:list, requests:create, requests:read and audit:read. The scopes table says what each allows.

Ask only for what your app needs. A token can never do more than the person’s current role allows: the role is checked on every request, so someone who is made a viewer loses scopes at once, and someone who leaves the organisation loses access.

Errors and limits

The token endpoint answers errors as { "error": "…", "error_description": "…" }, with invalid_request, invalid_client, invalid_grant, invalid_scope or unsupported_grant_type. Treat invalid_grant on a refresh as signed out.

  • 401 with WWW-Authenticate: Bearer error="invalid_token": the token expired, was revoked or is unknown. Refresh once; if that fails, ask the person to sign in again.
  • 403 INSUFFICIENT_SCOPE: the token lacks the scope. Tell the person; don’t retry.
  • Rate limits: the token, revocation and introspection endpoints allow 120 requests per IP a minute between them, and authorization 60. People behind one office network share an IP, so don’t refresh more often than you need to, and back off after a failure.

The rest of the API’s errors and limits are the same as with a key: see Integrations.

Checklist

The rules ShareShield’s own browser extension follows, and a good list for any public client:

  • A fresh code_verifier and state from a secure random source for every sign-in.
  • Reject the redirect unless state and iss match.
  • The same redirect_uri on the authorization and token requests.
  • Endpoints from the metadata document, not hard-coded paths.
  • Request only the scopes you use, and switch features off when a scope isn’t granted.
  • Keep tokens where web pages and other sites can’t read them, and never log tokens, codes or verifiers.
  • One refresh at a time, with back-off instead of tight retries.
  • On sign-out, revoke the refresh token, then delete every token whatever the result.

The OAuth section of the API reference is the source of truth. If this page ever disagrees with it, the reference is right.