OAuth Applications

Shocking Energy supports OAuth 2.1 for secure third-party access to team data. OAuth applications allow external services to request access on behalf of a user, with explicit consent and scoped permissions.

When to use OAuth

OAuth is ideal when:

• A third-party service needs to access team data on behalf of a user
• You want users to approve specific permissions before granting access
• You need time-limited tokens that can be refreshed automatically

How OAuth works

Shocking Energy implements the OAuth 2.1 Authorization Code flow with PKCE (Proof Key for Code Exchange).

Create an OAuth application

OAuth endpoints

All endpoints are relative to your API base URL (e.g. https://api.jobway.ai).

Discovery

Authorization flow

Authorization request

Redirect the user to the authorization endpoint:

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://example.com/callback&
  scope=jobs.read+flows.read+team.read&
  code_challenge=BASE64URL_ENCODED_CHALLENGE&
  code_challenge_method=S256&
  state=RANDOM_CSRF_TOKEN

Token exchange

Exchange the authorization code for tokens:

curl -X POST https://api.jobway.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://example.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Response:

{
  "access_token": "se_oauth_...",
  "refresh_token": "se_rt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "jobs.read flows.read team.read"
}

Refresh tokens

Access tokens expire after 2 hours. Use the refresh token to obtain a new access token:

curl -X POST https://api.jobway.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Revoke tokens

Revoke an access or refresh token when it is no longer needed:

curl -X POST https://api.jobway.ai/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE"

The revoke endpoint always returns 200 OK regardless of whether the token was valid.

Dynamic client registration

MCP-compatible AI clients like Claude.ai can register themselves automatically via the registration endpoint (no pre-created client ID required). Claude Connectors use this DCR flow when you add a custom connector URL:

curl -X POST https://api.jobway.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My AI Assistant",
    "redirect_uris": ["https://example.com/callback"],
    "scope": "jobs.read flows.read team.read",
    "token_endpoint_auth_method": "none"
  }'

Set token_endpoint_auth_method to "none" for public clients (e.g. single-page apps, CLI tools) that cannot securely store a client secret. Public clients must use PKCE.

Public vs confidential clients

Security considerations

• PKCE is mandatory for public clients — prevents authorization code interception attacks
• Redirect URIs are validated — only registered URIs are accepted
• Client secrets are hashed — stored using SHA-256, never in plain text
• Rate limiting — token and registration endpoints are rate-limited to 20 requests per 15 minutes
• Token revocation — users and applications can revoke tokens at any time
• Scope restriction — tokens can only access resources within their granted scopes