CLI OAuth

Sessions, contexts, and tokens#

One browser approval creates a session. A session holds one or more contexts, and each context is one merchant in one mode: its live account, or one of its sandboxes. The person who approves chooses the contexts and the scopes each one holds.

The session keeps its oauth_session_id through every refresh and consent change. Each context has a context_id whose merchant, mode, and sandbox never change. If a consent review removes a context and a later review in the same session approves that merchant and sandbox again, the context returns with its original ID.

A session ends 30 days after its last token was issued, 90 days after login, when any of its tokens is revoked, or when a spent refresh token is reused. Ending the session invalidates every token in every context.

Requests and responses#

These rules apply to the three CLI OAuth endpoints and to the CLI's use of the shared token and revocation endpoints:

• Send an application/x-www-form-urlencoded body, with each field once and no URL query string. Anything else returns 400 invalid_request. The device authorization and consent review endpoints also reject fields they don't define.
• Send client_id=flint-cli, with no client_secret and no Authorization header. Otherwise the request fails with 401 invalid_client.
• Responses are flat OAuth JSON without the Flint envelope, sent with Cache-Control: no-store. Flint never replays these requests from an idempotency cache.

Sign in#

Start the login#

curl https://api.withflintpay.com/v1/oauth/device/authorize \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "session_mode=contexts" \
  --data-urlencode "mode=test" \
  --data-urlencode "scope=payments.payment_intents.read payments.payment_intents.write"

{
  "device_code": "fcdc_example",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://app.withflintpay.com/cli/activate",
  "verification_uri_complete": "https://app.withflintpay.com/cli/activate?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

Open verification_uri_complete in the person's browser, or show verification_uri and user_code for them to open and type. The link only identifies the request; nothing is approved until the person approves it.

What the person approves#

The person signs in to the dashboard, checks that the code matches, and chooses contexts. Flint starts them on a likely context, and they can add other sandboxes, other merchants, or live access, or remove scopes, before they approve or deny. Live contexts carry a live label.

Each approved context needs at least one scope, and only scopes from your request. A scope that a mode doesn't allow, such as a live-only scope in a sandbox, can't be granted in that mode. A session can track up to 100 contexts, including ones later removed.

Poll for tokens#

Poll the token endpoint with the device code, waiting interval seconds between requests:

curl https://api.withflintpay.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "device_code=$DEVICE_CODE"

Until the login finishes, each poll returns 400 with one of these error values:

Once the person approves, the next poll returns the session's first tokens:

{
  "access_token": "fcat_example",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "fcrt_example",
  "scope": "payments.payment_intents.read payments.payment_intents.write",
  "oauth_session_id": "session_example",
  "context_id": "ctx_example"
}

scope lists what the person granted to this context, which can be fewer scopes than you asked for. Store the refresh token as a secret; the Flint CLI keeps it in the OS keychain.

Call the API#

Send the access token in the Authorization header. It acts only in its context, so you don't need Flint-Mode or Flint-Sandbox-Id. GET /v1/auth-context shows which context a token belongs to:

curl https://api.withflintpay.com/v1/auth-context \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": {
    "auth_type": "oauth",
    "oauth_session_id": "session_example",
    "context_id": "ctx_example",
    "oauth_grant_id": "clg_01KEZF7C00Q6S9W2D8HF4YBN3T",
    "name": "Example store",
    "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
    "environment": "sandbox",
    "sandbox_id": "test_01KEZF7C00JVWYYN2SBWFFSA36",
    "scopes": [
      "payments.payment_intents.read",
      "payments.payment_intents.write"
    ]
  },
  "request_id": "req_01KWM64QRVW8VG2M0B0BAHH3Q3"
}

oauth_grant_id identifies the context's grant and stays the same across refreshes and consent changes. API requests made with a CLI token return the usual Flint error envelope:

Refresh and switch contexts#

Refresh to get a new access token for any context in the session. Naming a different context_id is how you switch contexts.

curl https://api.withflintpay.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN" \
  --data-urlencode "context_id=ctx_example"

The response has the same fields as the login response, with a new access_token and refresh_token.

• Access tokens issued earlier keep working until they expire, in every context. A refresh doesn't revoke them.
• invalid_context means context_id is missing or isn't part of this session. context_access_denied means consent removed the context, or the person lost access to it. Neither error uses up the refresh token: list the contexts and refresh for one of them.
• invalid_grant means the session has ended. Start a new login.
• Each refresh restarts the 30-day idle period. Near the 90-day limit, expires_in is shorter than 900 seconds.

List the contexts#

curl https://api.withflintpay.com/v1/oauth/contexts \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

{
  "oauth_session_id": "session_example",
  "contexts": [
    {
      "id": "ctx_example",
      "name": "Example store",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "environment": "sandbox",
      "sandbox_id": "test_01KEZF7C00JVWYYN2SBWFFSA36"
    },
    {
      "id": "ctx_example_live",
      "name": "Example store",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "environment": "live"
    }
  ]
}

Send the current refresh token. Listing checks it without replacing it, so it works while the access token is expired. It grants no API access and doesn't return scopes; read those from a token response's scope or from GET /v1/auth-context.

environment is sandbox for a test-mode context, which also has sandbox_id, and live for a live one. The list holds only contexts the person can still use, in the order they were last approved, with no pagination. An empty list means no context is usable; review consent to add one.

Change what a session can access#

POST /v1/oauth/device/reauthorize starts a new browser approval for an existing session. Send the current refresh token and session_mode=contexts. The response, the browser step, and polling work as they do at login. Starting a review changes nothing, and a denied or expired review leaves the session as it was. Redeeming the device code for a superseded review returns 400 expired_token; start a new review. The existing session remains active.

There are two kinds of review:

To add scopes to one context:

curl https://api.withflintpay.com/v1/oauth/device/reauthorize \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN" \
  --data-urlencode "session_mode=contexts" \
  --data-urlencode "scope_mode=additive" \
  --data-urlencode "context_id=ctx_example" \
  --data-urlencode "scope=commerce.subscriptions.read"

merchant_id and sandbox_id limit a full review's contexts as they do at login. An additive review takes its merchant and mode from the context, so a merchant_id, sandbox_id, or mode that disagrees returns invalid_context, and a context the session no longer holds returns context_access_denied.

Redeem the review's device code at the token endpoint as you would at login. Redemption:

• Keeps oauth_session_id and replaces the session's refresh token. Discard the refresh token you started the review with: sending it afterward ends the session.
• Returns an access token for context_id while that context remains. Otherwise the token is for a sandbox context, so a full review must keep context_id's context or at least one sandbox context.
• Reports in scope what the person granted, which can be a subset of what you asked for.

Approving a review cancels every other review of the same session that hasn't been redeemed yet. Start a new review if you still need one.

Sign out#

Revoke any access or refresh token from the session, including a refresh token that was already replaced:

curl https://api.withflintpay.com/v1/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=flint-cli" \
  --data-urlencode "token=$REFRESH_TOKEN" \
  --data-urlencode "token_type_hint=refresh_token"

A 200 with an empty body means the session has ended, whether this request ended it or it had already ended. An unknown token also returns 200. Every token in every context stops working, and webhook event streams opened with them close. People can also review and end their sessions on the dashboard's CLI sessions page.

OAuth errors#

Every call above returns failures as error with a fixed error_description. Branch on error; the description is for people.

Related#