generated: '2026-09-04' method: searched source: https://docs.worksome.com/authentication/ docs: https://docs.worksome.com/authentication/ note: >- Derived from the published Authentication page rather than from an OpenAPI securitySchemes block — Worksome publishes no OpenAPI. The API is GraphQL-only and every authenticated call carries a standard Authorization: Bearer header against the single endpoint https://api.worksome.com/graphql. Two token sources exist: OAuth 2.0 authorization code (the preferred path, for acting on behalf of other users) and Personal Access Tokens (for testing and single-account integrations). Note that schema INTROSPECTION is open and unauthenticated — an anonymous POST of the introspection query to the endpoint returns the full 496-type schema — while every data-bearing query and mutation requires a token. transport: tls_required: true endpoint: https://api.worksome.com/graphql method: POST content_type_required: application/json csrf_note: >- The Apollo federation gateway enforces CSRF preflight. A POST without Content-Type: application/json, or any GET without an apollo-require-preflight (or x-apollo-operation-name) header, is rejected with extensions.code BAD_REQUEST before the request reaches GraphQL. schemes: - id: oauth2_authorization_code type: oauth2 flow: authorizationCode preferred: true authorization_url: https://use.worksome.com/oauth/authorize token_url: https://use.worksome.com/oauth/token refresh_supported: true refresh_grant_type: refresh_token pkce: not documented client_registration: >- Self-service via the Worksome API clients page. A client carries a name and a redirect (callback) URL; only the registered redirect URL is accepted at authorization time. authorize_parameters: - name: client_id required: true type: string - name: response_type required: true type: string value: code - name: redirect_uri required: true type: string - name: state required: false type: string description: Unguessable random string; CSRF protection. Docs instruct aborting if the returned state does not match. - name: prompt required: false type: string enum: [consent, login] description: consent always shows the approval screen; login always forces re-authentication; omitted means prompt only if not previously authorized. token_parameters: [client_id, client_secret, code, grant_type, redirect_uri] token_response_fields: [token_type, expires_in, access_token, refresh_token] code_lifetime: 10 minutes access_token_lifetime: 15 days refresh_window: 90 days scopes_published: false scopes_note: >- No scope parameter is documented on the authorize call and no scope reference page is published, so no scopes/ artifact is emitted. The docs do acknowledge scopes exist at the failure end — a listed cause of authorization failure is "The token does not have the required scopes" — which means an integrator can be denied by a scope they were never shown. This is a real documentation gap, not an absence of the mechanism. revocation: >- A client can be revoked from the API clients page, which both blocks new token issuance and invalidates tokens already issued by that client. - id: personal_access_token type: http scheme: bearer bearer_format: opaque preferred: false intended_use: Testing and single-account integrations; also the CLI's only supported credential. issuance: Self-service from the Worksome API tokens page. lifetime: 6 months from creation, automatically revoked on expiry revocation: Manual, from the API tokens page. header: 'Authorization: Bearer {token}' authorization_model: tenancy: >- A token belongs to a user, and a user may have access to multiple accounts. The viewer query returns the authenticated user; the top-level accounts query returns the accounts the token can act on. accounts returns an Account interface implemented by Company, Organisation, Partner, StaffingAgency and Worker — most company-context operations require a Company id. Cross-company access is denied, and the docs list "wrong company scope" as a distinct authorization failure cause. field_level: >- Authorization is enforced per field, not only per operation. A field the token may not read returns null inside data with a matching entry in the errors array, so a partial success is the normal shape of an under-privileged query. roles: >- Role names are not published. The docs reference "the required role (e.g., manager, admin)" as an example only. multi_factor: available: true note: >- The GraphQL schema exposes end-user MFA management — createSmsMultiFactor, verifySmsMultiFactor, createTotpMultiFactor, verifyTotpMultiFactor, removeMultiFactor, and multiFactor/multiFactors queries. This is MFA for platform users managed through the API, not a second factor on API token authentication itself. methods: [sms, totp] source: graphql/worksome.graphql sso: available: true protocol: SAML note: SSO/SAML is named as an included platform capability on the pricing page. No SAML metadata endpoint or configuration reference is published in the developer docs. source: https://www.worksome.com/pricing webhook_authentication: direction: inbound-to-consumer mechanism: HMAC-SHA256 header: Signature secret: Shared secret agreed with Worksome out of band verification: hash_hmac('sha256', raw_body, secret) compared in constant time against the Signature header note: >- The signature covers the RAW request body — the docs are explicit that the body must be read and verified before it is parsed. The header carries a bare hex digest with no timestamp and no version prefix, so there is no replay window bound to the signature itself; the docs instead put the burden on the consumer, requiring handlers to be idempotent and to detect duplicates by entity id. source: https://docs.worksome.com/webhooks/guides/handle-webhooks/ failure_modes: - condition: Missing or invalid bearer token code: DOWNSTREAM_SERVICE_ERROR http: 200 discriminator: 'extensions.guards == ["api"] AND message == "Unauthenticated."' - condition: Valid token, operation not permitted code: DOWNSTREAM_SERVICE_ERROR http: 200 discriminator: No validation map, no guards; message "You are not authorized to perform this action." with the operation in path. - condition: Expired or revoked token code: DOWNSTREAM_SERVICE_ERROR http: 200 remediation: Issue a new PAT (6-month lifetime) or refresh the OAuth token.