Who this is for
Part of the Homeworks Connect documentation. See Homeworks Connect: All Integration Options for the full picture.
Developers building integrations on the Homeworks API. You’ll register your app via the self-serve endpoint in Step 1 below — no approval or account manager required.
Step 1: Register Your App (One-Time)
POST to the registration endpoint once per app per environment. Returns a client_id — save it. No client_secret; PKCE is the security mechanism.
Production
POST <https://api.home.works/oauth/register> Content-Type: application/json { "client_name": "My App Name", "redirect_uris": ["<https://your-app.example.com/callback>"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"] }
Response
{ "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "client_name": "My App Name", "redirect_uris": ["<https://your-app.example.com/callback>"] }
Save the client_id — you need it for every subsequent request. There is no client_secret; PKCE is the security mechanism.
Flow overview
Homeworks uses OAuth 2.1 with PKCE (no client secrets). The flow:
Generate a code verifier + code challenge (PKCE)
Redirect the user to the Homeworks authorization endpoint
Receive the authorization code on your redirect URI
Exchange the code + verifier for an access token and refresh token
Use the access token as a Bearer token on all API requests
When the access token expires, use the refresh token to get a new one
Endpoints
Authorization: https://api.home.works/oauth/authorize
Token exchange: https://api.home.works/oauth/token
Auto-discovery: https://api.home.works/.well-known/oauth-authorization-server
Authorization request (step 2)
GET /oauth/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=YOUR_REDIRECT_URI &response_type=code &code_challenge=YOUR_CHALLENGE &code_challenge_method=S256 &scope=openid%20company
Receive the authorization code (step 3)
After the user approves, Homeworks redirects them to your redirect_uri with the authorization code as a query parameter:
<https://your-app.example.com/callback?code=AUTH_CODE&state=YOUR_STATE>
Extract the code parameter from the URL — you’ll pass it to the token endpoint in step 4. If you included a state parameter in step 2, validate it here to protect against CSRF.
Token exchange (step 4)
POST /oauth/token client_id=YOUR_CLIENT_ID &grant_type=authorization_code &code=AUTH_CODE &redirect_uri=YOUR_REDIRECT_URI &code_verifier=YOUR_VERIFIER
Token refresh
POST /oauth/token client_id=YOUR_CLIENT_ID &grant_type=refresh_token &refresh_token=YOUR_REFRESH_TOKEN
Token lifetimes: access tokens expire after 1 hour. Refresh tokens are valid for 14 days. When an access token expires, use the refresh token endpoint above to obtain a new one. Refresh tokens rotate on each use — store the new refresh token returned with each response.
Using your token
All API requests require: Authorization: Bearer <access_token>
JWT claims
The access token is a signed RS256 JWT. Verify the signature using the JWKS endpoint from auto-discovery. Claims:
sub — user ID (string)
type — "COMPANY"
username — user email address
userId — numeric user ID
companyId — the Homeworks company this token belongs to (store this!)
role — user’s role within the company
scope — "company"
iss — https://api.home.works
iat / exp — issued-at and expiry timestamps
Access tiers
API access requires an Enterprise plan or an active Growth trial.
Auto-Discovery
Point your OAuth client at the discovery endpoint and it returns all the URLs you need:
GET <https://api.home.works/.well-known/oauth-authorization-server>
Returns: authorization_endpoint, token_endpoint, jwks_uri, registration_endpoint, and supported scopes and grant types.
GraphQL Schema / Introspection
Introspection is disabled in production for security reason. Options:
SDL export available as a reference (may not reflect the latest schema — contact the Homeworks team for the current version)
MCP clients (Claude, Cursor, etc.): point at the MCP server URL — it self-configures from the live schema automatically