OAuth

The Contractors Cloud API supports two ways to authenticate: a long-lived API access token for a single account’s own integrations, and OAuth 2.0 for applications and AI agents that connect on behalf of a Contractors Cloud user without ever seeing their password. Use OAuth when you’re building something other people install and connect to their own Contractors Cloud account — a third-party application, or an AI agent connecting through MCP.

What OAuth is used for

OAuth here follows the standard authorization code grant with PKCE. A user signs in and approves your application once; your application then holds a short-lived access token (plus a longer-lived refresh token) that acts as that user for as long as they stay connected. Every request made with the resulting token is scoped to that one user’s permissions and organization, the same as if they were using the API directly.

Getting a client

OAuth clients for MCP platforms register themselves automatically through dynamic client registration — most AI agents need no manual setup at all. Self-service creation of OAuth clients for general integrations is coming to the Contractors Cloud web app. Until then, contact Contractors Cloud support to have a client provisioned for your integration.

The authorization flow

Request authorization

Redirect the user’s browser to the authorize endpoint:

GET https://api.contractorscloud.com/api/v1/oauth/authorize

Parameter	Type	Required	Description
`client_id`	string (UUID)	Yes	Your OAuth client’s ID.
`redirect_uri`	string	Yes	Where the user is sent after approving or denying access. Must exactly match one of your client’s registered redirect URIs.
`response_type`	string	Yes	Must be `code`.
`scope`	string	No	Space-separated list of requested scopes, for example `read write`.
`state`	string	Recommended	An opaque value your application generates and verifies on callback, to guard against CSRF.
`code_challenge`	string	Public clients: yes	The PKCE code challenge derived from your `code_verifier`. See PKCE for public clients.
`code_challenge_method`	string	With `code_challenge`	Must be `S256`.

https://api.contractorscloud.com/api/v1/oauth/authorize
  ?client_id=9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b
  &redirect_uri=https://myapp.example.com/callback
  &response_type=code
  &scope=read write
  &state=random-csrf-token

If the user isn’t signed in, they land on the Contractors Cloud login page, then continue on to consent after signing in.
If they’re already signed in, they see a consent screen listing your application and the scopes it’s requesting, with Approve and Deny buttons.
If they’ve previously approved this exact client and scope combination, the consent screen is skipped and they’re redirected straight back to your redirect_uri with a fresh authorization code.

The callback

On approval, the user’s browser is redirected to your redirect_uri with a code and the state you sent:

https://myapp.example.com/callback?code=def502...&state=random-csrf-token

If the user denies the request instead, the redirect carries error=access_denied. Verify the returned state matches what you sent before you do anything else with the code.

Exchange the code for tokens

POST https://api.contractorscloud.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

Field	Type	Required	Description
`grant_type`	string	Yes	Must be `authorization_code`.
`client_id`	string (UUID)	Yes	Your OAuth client’s ID.
`client_secret`	string	Confidential clients	Your client secret. Public clients authenticate with PKCE instead.
`redirect_uri`	string	Yes	Must match the URI used in the authorization request.
`code`	string	Yes	The authorization code from the callback.
`code_verifier`	string	Public clients: yes	The plain PKCE verifier whose challenge was sent in the authorization request.

curl -X POST "https://api.contractorscloud.com/api/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://myapp.example.com/callback" \
  -d "code=def502..."

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6..."
}

Treat client_secret and refresh_token values as credentials — store them the way you’d store any other secret. Never expose them in client-side code or commit them to a public repository.

Using the access token

Include the access token as a bearer token on every API request:

curl "https://api.contractorscloud.com/api/v1/projects" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."

Refreshing an access token

When the access token expires, exchange the refresh token for a new pair instead of asking the user to sign in again:

curl -X POST "https://api.contractorscloud.com/api/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=def50200a1b2c3d4e5f6..."

The response has the same shape as the initial token exchange. Both the access token and the refresh token are rotated on every refresh — the old refresh token is invalidated, so store the new one and discard the old.

Token lifetimes

Token	Lifetime
Access token	1 hour
Refresh token	30 days

Scopes

Scope	Description
`read`	Read access to your organization’s resources.
`write`	Write access to your organization’s resources.
`mcp:use`	Access the MCP server as the authorizing user. Required to connect an AI agent — see Connect your AI agent.

Request the minimal scopes you need — only ask for the read, write, or mcp:use scopes your application actually uses.

PKCE for public clients

Public clients — those without a client secret — must use PKCE (RFC 7636) on every authorization request:

Generate a random code_verifier: 43–128 characters from A-Z, a-z, 0-9, -, ., _, ~.
Derive code_challenge = base64url(sha256(code_verifier)) and send it, along with code_challenge_method=S256, on the authorization request.
Send the original code_verifier (not the challenge) in the token exchange, in place of a client_secret.

Only S256 is accepted — plain (or an omitted code_challenge_method) is rejected with an invalid_request error, as is an authorization request from a public client with no code_challenge at all. Confidential clients (those with a secret) can use PKCE too, as defense in depth, but it’s optional for them.

Dynamic client registration

MCP clients that discover the registration_endpoint from discovery can self-provision an OAuth client automatically, with no manual setup:

curl -X POST "https://api.contractorscloud.com/api/v1/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My MCP Client", "redirect_uris": ["http://localhost/callback"]}'

{
  "client_id": "9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
  "redirect_uris": ["http://localhost/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "mcp:use",
  "token_endpoint_auth_method": "none"
}

Every dynamically registered client is public — no secret is issued, so PKCE is required on every authorization request — and is limited to the mcp:use scope. A client registered this way can connect an AI agent through MCP, but can’t request read or write access. redirect_uris must use callback addresses from approved platforms — contact support to add yours. Native clients (such as Claude Code) that receive the OAuth callback on a loopback address use an ephemeral port chosen at connect time, so the exact port isn’t known when the client registers. A loopback redirect URI (http://localhost, http://127.0.0.1) matches regardless of port — register once, and connect using whichever port your client happens to bind that session.

Discovery

Method	Endpoint	Purpose
`GET`	`/.well-known/oauth-protected-resource/mcp`	Protected resource metadata — which authorization server protects the MCP endpoint and which scopes it supports.
`GET`	`/.well-known/oauth-authorization-server`	Authorization server metadata — the authorize, token, and registration endpoints, supported PKCE methods, grant types, and scopes.

Both are unauthenticated and let a compliant client bootstrap the OAuth flow without any out-of-band configuration. An unauthenticated request to the MCP endpoint returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata URL:

{
  "issuer": "https://api.contractorscloud.com",
  "authorization_endpoint": "https://api.contractorscloud.com/api/v1/oauth/authorize",
  "token_endpoint": "https://api.contractorscloud.com/api/v1/oauth/token",
  "registration_endpoint": "https://api.contractorscloud.com/api/v1/oauth/register",
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "scopes_supported": ["read", "write", "mcp:use"]
}

Client credentials grant

The client-credentials grant isn’t a supported integration path for this API. It doesn’t identify a user, and every endpoint here requires a token that acts on behalf of a specific person. Use the authorization flow above, even for server-to-server integrations, so requests always run as a real user in the target organization.

Errors

OAuth error responses follow the RFC 6749 format:

{
  "error": "invalid_grant",
  "error_description": "The authorization code has been revoked.",
  "message": "The authorization code has been revoked."
}

Error	HTTP status	Description
`invalid_request`	400	Missing or invalid parameter.
`invalid_client`	401	Client authentication failed (bad client ID or secret).
`invalid_grant`	400	The authorization code or refresh token is invalid, expired, or revoked.
`unsupported_grant_type`	400	The grant type isn’t supported.
`invalid_scope`	400	The requested scope is unknown.
`access_denied`	403	The user denied the authorization request.

See Connect your AI agent for the end-user walkthrough of connecting Claude, ChatGPT, and other MCP clients over this flow.

Concepts

Domains

Examples

What OAuth is used for

Getting a client

The authorization flow

Request authorization

The callback

Exchange the code for tokens

Using the access token

Refreshing an access token

Token lifetimes

Scopes

PKCE for public clients

Dynamic client registration

Discovery

Client credentials grant

Errors

​What OAuth is used for

​Getting a client

​The authorization flow

​Request authorization

​Hosted login and consent

​The callback

​Exchange the code for tokens

​Using the access token

​Refreshing an access token

​Token lifetimes

​Scopes

​PKCE for public clients

​Dynamic client registration

​Discovery

​Client credentials grant

​Errors

What OAuth is used for

Getting a client

The authorization flow

Request authorization

Hosted login and consent

The callback

Exchange the code for tokens

Using the access token

Refreshing an access token

Token lifetimes

Scopes

PKCE for public clients

Dynamic client registration

Discovery

Client credentials grant

Errors