Skip to content
HarperHarborDocs

Start the authorization-code flow (PKCE S256 required)

GET
/oauth/authorize
curl --request GET \
  --url 'https://api.harperharbor.com/oauth/authorize?response_type=code&client_id=example&redirect_uri=https%3A%2F%2Fexample.com&code_challenge=example&code_challenge_method=S256&resource=%3CAPI_BASE%3E%2Fopen%2Fv1&scope=mcp%3Acard-writer'

Validates the request, stores it for 10 minutes and redirects (302) the browser to the HarperHarbor login/consent page (the provider’s Console with oauth_request=<id>. After the user logs in and approves/denies (the consent page uses the internal endpoints POST /oauth/authorize/context and POST /oauth/authorize/complete, which require a HarperHarbor Console session and are not part of the client-facing contract), the browser is redirected to redirect_uri with code and state (approve), or error=access_denied and state (deny), or error=temporarily_unavailable if the request expired. The authorization code is valid for 10 minutes and single-use. Validation failures of this endpoint itself are returned as 400 JSON, not as an error redirect.

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
response_type
required
string
Allowed values: code
client_id
required
string

From /oauth/register.

redirect_uri
required
string format: uri

Must exactly match one registered redirect URI.

code_challenge
required
string

PKCE challenge: base64url(SHA-256(code_verifier)), no padding.

code_challenge_method
required
string
Allowed values: S256
resource
required
string
Allowed values: <API_BASE>/open/v1 <API_BASE>/mcp/card-writer

Resource indicator (RFC 8707). Use <API_BASE>/open/v1 for the Open API; the token is only valid on that resource.

scope
string
default: mcp:card-writer
Allowed values: mcp:card-writer

Only the single scope exists; omit or send exactly this value.

state
string

Opaque value echoed back on the redirect.

login_site
string

Send pro to use the alternate login domain (for regions where the main domain is blocked). Any other value is ignored.

Responses

Section titled “Responses”

302

Section titled “302”

Redirect to the login/consent page. Later the user agent is redirected to redirect_uri?code=...&state=... or redirect_uri?error=access_denied&state=....

400

Section titled “400”

unsupported_response_type, invalid_client, invalid_redirect_uri, unsupported_pkce, invalid_scope, invalid_resource.

Media typeapplication/json
object
error
required

OAuth error code.

string
redirect_url

Only on the internal consent endpoints when the request expired.

string
retry_after

Seconds to wait before trying again; only with rate_limited.

integer
Examplegenerated
{
  "error": "example",
  "redirect_url": "example",
  "retry_after": 1
}