WorkSights · Developer documentation

Build with the WorkSights REST API

The versioned /api/v1 surface gives your own code the same view of your data you have in WorkSights - always scoped to what your account can see. Authentication is OAuth 2.1; you register an app once and exchange it for access tokens.

1. Register an app

1. Sign in to WorkSights and open your user profile and then click the Developer tab.
2. Choose Register app, give it a name, and add the redirect URI(s) your integration (or Postman) will use. https is required; http://localhost is allowed for development.
3. Copy the Client ID and Client secret shown on creation. The secret is displayed once - store it somewhere safe. If it's lost, regenerate it from the same tab (which invalidates the old one).

Apps you register are private: only you (and admins of your account, for offboarding) can manage them, and only you or your teammates can authorize them. This is a confidential client - it keeps a secret - so run it from a backend, not a browser or a shipped binary.

2. Get an access token

Use the standard OAuth 2.1 authorization-code flow with PKCE. Your confidential client authenticates at the token endpoint with client_secret_basic (HTTP Basic: client_id:client_secret). A user approves the connection once, and you receive an access_token plus a rotating refresh_token.

The exact authorization and token endpoints are listed in your OAuth authorization-server discovery document and in the Endpoints & agent kit panel of the Developer tab - copy them from there so you always have the right URLs for your region. That panel also has a Copy agent prompt button that packages all of this for an AI coding assistant.

The token exchange is a standard authorization-code request - client credentials go in the Authorization header (HTTP Basic), the PKCE verifier in the body:

POST https://vault.ascendius.com/auth/v1/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization code>
&redirect_uri=<your registered redirect uri>
&code_verifier=<pkce verifier>

The host shown is the US region (vault.ascendius.com); EU accounts use eu-vault.ascendius.com. The exact authorization and token URLs for your account are always shown in the Endpoints & agent kit panel of your Developer tab - copy them from there.

3. Call the API

Send the access token as a bearer token against https://app.worksights.ai/api/v1:

Every endpoint, its parameters, and response shapes are in the WorkSights API reference (OpenAPI). Requests run as the user who authorized the app and are read-only.

4. Keep it running

Access tokens are short-lived. Exchange your refresh_token for a new access token when it expires - and persist the new refresh token each time, because refresh tokens rotate on use. Losing the latest refresh token means re-authorizing.

Just testing?

For a quick call from Postman or curl without building the OAuth flow, use Copy test token in the Developer tab. It hands you your current session token - good for ~an hour, no refresh - so you can hit https://app.worksights.ai/api/v1/me immediately. Register an app for anything beyond throwaway testing.

Access, security, and limits

• Your permissions, exactly. Calls see only the data your WorkSights account can see, and are read-only.
• Rate limits. 60 requests per minute per token.
• Audit trail. Every request is logged with your identity and the app that made it.
• Revoking access. Delete the app from the Developer tab, or revoke a specific connection from your connected-apps settings - tokens stop working once revoked.