Build on the network

1. 1

   Create a key in developer settings. Give it a name and only the scopes it needs, and an expiry if it is for something temporary.

   Until your e-mail address is confirmed, a key can only carry the read scopes.

2. 2

   Copy the key when it is shown. It appears once: only a fingerprint of it is kept, so a lost key cannot be recovered, only replaced.

3. 3

   Send it as a bearer token on every request:

   shell

   curl https://api.thecubefloor.com/v1/me \
     -H "Authorization: Bearer dk_…"

   Copy
4. 4

   Revoke it from the same page the moment it is no longer needed. The list shows when each key was last used.

The authorization code grant, with PKCE (S256) required on every request. Every app is a confidential client with a secret.

1. 1

   Register the app in developer settings: its name (people see it when they are asked), its redirect URIs and the scopes it may ask for. You get a client_id and a client_secret, the secret shown once. Registering an app needs a confirmed e-mail address.

   Redirect URIs must match character for character. They are absolute https:// addresses without a fragment; plain http:// is accepted only to localhost or a loopback address, for development and native apps.

2. 2

   Make a random code_verifier and send the person’s browser to /oauth/authorize with its SHA-256 as code_challenge:

   shell

   # A verifier: 43 to 128 unreserved characters. Keep it until the exchange.
   CODE_VERIFIER=$(openssl rand -base64 64 | tr -dc 'A-Za-z0-9' | cut -c1-64)
   CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary \
     | openssl base64 -A | tr '+/' '-_' | tr -d '=')
   
   https://api.thecubefloor.com/oauth/authorize?response_type=code
     &client_id=app_…
     &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
     &scope=account%3Aread%20jobs%3Aread
     &state=…
     &code_challenge=$CODE_CHALLENGE
     &code_challenge_method=S256

   Copy
3. 3

   They see our consent page on thecubefloor.com, with your app’s name, what it asks for and where it will return. If they approve, the browser comes back to your redirect URI with code and your state; if they decline, with error=access_denied.

4. 4

   Trade the code, within a minute and once only, for tokens. Authenticate with HTTP Basic or with client_id and client_secret in the form:

   shell

   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri=https://your.app/callback \
     -d code_verifier="$CODE_VERIFIER"

   Copy
5. 5

   The answer holds an access token (do_…, good for an hour) and a refresh token (dr_…, thirty days). Each refresh spends the refresh token and returns a new pair; presenting a spent one ends every token from the same approval, since one of its two holders is a thief.

   json · shell

   {
     "access_token": "do_…",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "dr_…",
     "scope": "account:read jobs:read"
   }
   
   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=refresh_token \
     -d refresh_token="$REFRESH_TOKEN"

   Copy
6. 6

   When the person disconnects in your app, give the token back (RFC 7009). A refresh token ends the whole approval:

   shell

   curl https://api.thecubefloor.com/oauth/revoke \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d token="$REFRESH_TOKEN"

   Copy