OAuth authorization code with PKCE

This flow lets an organization owner or admin approve access for a hosted, confidential web application. The person signs in with INSIDE HUB and chooses which scopes and websites to grant.

Requirements

• The application is a confidential client. It keeps the client secret on its server and authenticates to the token endpoint with HTTP Basic.
• Its callback URLs are registered on the credential under OAuth callbacks in the console: up to 10 exact HTTPS URLs.
• It uses PKCE with S256, and a state of 16 to 1024 printable ASCII characters.

Not for desktop or command-line agents

Public clients, http:// and loopback callbacks, and dynamic client registration aren’t supported. Desktop and command-line AI agents therefore can’t use this flow. Use an installation token or client credentials instead.

Flow

1. Send the person to the authorization endpoint.

   https://api.inside.chat/oauth/authorize
     ?response_type=code
     &client_id=<credential_id>
     &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
     &resource=https%3A%2F%2Fapi.inside.chat
     &scope=website_read%20conversation_read
     &state=<random state>
     &code_challenge=<base64url SHA-256 of the verifier>
     &code_challenge_method=S256

   All of these parameters are required, and unknown or duplicate parameters are rejected. The consent page starts with every scope and website unchecked; the person selects them explicitly. They can also tick Renew access to allow refresh tokens.

2. Handle the callback. On approval the browser returns to your callback with code, state and iss. On denial it returns error=access_denied. Check that state matches. Codes expire within 2 minutes.

3. Exchange the code.

   curl -s https://api.inside.chat/oauth/token \
     -u "$INSIDE_CLIENT_ID:$INSIDE_CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d "code=$CODE" \
     --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
     -d "code_verifier=$VERIFIER" \
     --data-urlencode "resource=https://api.inside.chat"

   The access token lasts at most 15 minutes. If the person chose Renew access, the response also contains a refresh_token that starts with igr_live_ or igr_test_.

4. Refresh before the access token expires.

   curl -s https://api.inside.chat/oauth/token \
     -u "$INSIDE_CLIENT_ID:$INSIDE_CLIENT_SECRET" \
     -d grant_type=refresh_token \
     -d "refresh_token=$REFRESH_TOKEN" \
     --data-urlencode "resource=https://api.inside.chat"

Refresh rules

• Each refresh returns a new access token and a new refresh token. Store the new one and send refresh requests one at a time.
• Reusing an old refresh token revokes the whole consent and all of its tokens.
• Renewable consent lasts at most 8 hours, and a refresh family expires after 1 hour without use.

When access stops

• The consenting person loses their organization role or HUB account.
• An admin revokes the consent under OAuth consents in the console.
• The parent credential expires or is revoked.

Consent tokens can’t manage event subscriptions. Use an installation credential for those.