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
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_basicorclient_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.
| Purpose | Method and path |
|---|---|
| Server metadata (RFC 8414) | GET /.well-known/oauth-authorization-server |
| Authorization, in the browser | GET /oauth/authorize |
| Token (form-encoded) | POST /api/oauth/token |
| Revocation (RFC 7009) | POST /api/oauth/revoke |
| Introspection (RFC 7662), confidential clients only | POST /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:
# 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:
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
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
| Token | Prefix | Lifetime |
|---|---|---|
| Authorization code | ssac_ | 2 minutes, single use |
| Access token | ssat_ | 1 hour |
| Refresh token | ssrt_ | 30 days from its last use, replaced on every refresh |
| Client secret | sscs_ | Until rotated. Confidential clients only |
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.
401withWWW-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_verifierandstatefrom a secure random source for every sign-in. - Reject the redirect unless
stateandissmatch. - The same
redirect_urion 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.
