Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Identity

21 endpoints21 implementedAll modules →
  1. GET /rest/v1.0/auth/connected_appsList your connected apps
  2. DELETE /rest/v1.0/auth/connected_apps/{grant_id}Revoke one of your connected apps
  3. GET /rest/v1.0/companies/{company_id}/agent_activityNon-human API activity
  4. GET /rest/v1.0/companies/{company_id}/connected_appsList every app authorization in your company
  5. DELETE /rest/v1.0/companies/{company_id}/connected_apps/{grant_id}Revoke a person's app authorization
  6. GET /rest/v1.0/companies/{company_id}/oauth_appsList partner apps registered by your company
  7. POST /rest/v1.0/companies/{company_id}/oauth_appsRegister a partner app
  8. GET /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Show a partner app
  9. PATCH /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Update a partner app
  10. DELETE /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Retire a partner app
  11. GET /rest/v1.0/companies/{company_id}/service_accountsList service accounts
  12. POST /rest/v1.0/companies/{company_id}/service_accountsCreate a service account
  13. GET /rest/v1.0/companies/{company_id}/service_accounts/{id}Show a service account
  14. PATCH /rest/v1.0/companies/{company_id}/service_accounts/{id}Update or disable a service account
  15. GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/callsService account audit log
  16. GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsList credentials
  17. POST /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsCreate a credential
  18. DELETE /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}Revoke a credential
  19. POST /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}/rotateRotate a credential
  20. GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsList project access
  21. PUT /rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsSet project access
GET /rest/v1.0/auth/connected_apps

List your connected apps

Your own live authorizations. People only.

v1.0Implemented

Parameters

  • after
    stringquery

Response · 200 · object[]

  • id
    string (uuid)
  • user_id
    integer
  • user_name
    string | null
  • client_id
    string
  • client_name
    string
  • client_kind
    string
    One of: partner, mcp.
  • verified
    boolean
  • is_agent
    boolean
  • resource
    string
  • scopes
    string[]
  • created_at
    string (date-time)
  • expires_at
    string (date-time)

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/auth/connected_apps" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
DELETE /rest/v1.0/auth/connected_apps/{grant_id}

Revoke one of your connected apps

People only.

v1.0Implemented

Parameters

  • grant_id
    stringpathrequired
    Authorization id (uuid)
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Response · 204

No response body.

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/auth/connected_apps/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/agent_activity

Non-human API activity

Calls by service accounts, agents and partner apps, newest first. actor_type=agent&writes=true&outcome=allowed lists agent proposals awaiting human review; outcome=denied lists refused attempts.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • actor_type
    stringquery
    One of: service_account, agent, partner_app.
  • outcome
    stringquery
    One of: allowed, denied.
  • writes
    booleanquery
  • before
    stringquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    string
  • actor_type
    string
    One of: service_account, agent, partner_app.
  • actor_user_id
    integer
  • on_behalf_of_user_id
    integer | null
  • service_account_id
    integer | null
  • credential_ref
    string | null
  • client_id
    string | null
  • method
    string
  • route
    string | null
  • path
    string
  • action_class
    string | null
    One of: read, propose, approve, admin, null.
  • outcome
    string
    One of: allowed, denied.
  • denial_reason
    string | null
  • ip
    string | null
  • request_id
    string | null
  • created_at
    string (date-time)

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/agent_activity" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/connected_apps

List every app authorization in your company

Live authorizations of partner apps and MCP clients held by your company's people.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.

Response · 200 · object[]

  • id
    string (uuid)
  • user_id
    integer
  • user_name
    string | null
  • client_id
    string
  • client_name
    string
  • client_kind
    string
    One of: partner, mcp.
  • verified
    boolean
  • is_agent
    boolean
  • resource
    string
  • scopes
    string[]
  • created_at
    string (date-time)
  • expires_at
    string (date-time)

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connected_apps" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
DELETE /rest/v1.0/companies/{company_id}/connected_apps/{grant_id}

Revoke a person's app authorization

Ends the authorization and all its tokens now.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • grant_id
    stringpathrequired
    Authorization id (uuid)
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Response · 204

No response body.

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/connected_apps/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/oauth_apps

List partner apps registered by your company

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.

Response · 200 · object[]

  • client_id
    string
  • name
    string
  • description
    string | null
  • logo_url
    string | null
  • homepage_url
    string | null
  • redirect_uris
    string[]
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • verified
    boolean
  • is_agent
    boolean
  • company_id
    integer | null
  • status
    string
    One of: active, disabled, retired.
  • created_at
    string (date-time)
  • created_by_id
    integer | null
  • retired_at
    string (date-time) | null
  • token_endpoint_auth_method
    string

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/oauth_apps" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/oauth_apps

Register a partner app

Registers a public OAuth client (authorization code with PKCE S256, no client secret). Apps your company registers can only be authorized by your company's people. A platform review sets the verified badge.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Request body

  • oauth_app
    objectrequired
  • oauth_app.name
    stringrequired
  • oauth_app.description
    string | null
  • oauth_app.logo_url
    string | null
  • oauth_app.homepage_url
    string | null
  • oauth_app.redirect_uris
    string[]required
  • oauth_app.scopes
    string[]required
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • oauth_app.is_agent
    boolean

Response · 201 · object

  • client_id
    string
  • name
    string
  • description
    string | null
  • logo_url
    string | null
  • homepage_url
    string | null
  • redirect_uris
    string[]
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • verified
    boolean
  • is_agent
    boolean
  • company_id
    integer | null
  • status
    string
    One of: active, disabled, retired.
  • created_at
    string (date-time)
  • created_by_id
    integer | null
  • retired_at
    string (date-time) | null
  • token_endpoint_auth_method
    string

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 422Invalid fields

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/oauth_apps" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "oauth_app": {
    "name": "string",
    "redirect_uris": [],
    "scopes": []
  }
}'
GET /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}

Show a partner app

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • client_id
    stringpathrequired
    Partner app client id

Response · 200 · object

  • client_id
    string
  • name
    string
  • description
    string | null
  • logo_url
    string | null
  • homepage_url
    string | null
  • redirect_uris
    string[]
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • verified
    boolean
  • is_agent
    boolean
  • company_id
    integer | null
  • status
    string
    One of: active, disabled, retired.
  • created_at
    string (date-time)
  • created_by_id
    integer | null
  • retired_at
    string (date-time) | null
  • token_endpoint_auth_method
    string

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/oauth_apps/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}

Update a partner app

Narrowing scopes invalidates authorizations outside the new set at once; widening needs fresh consent. Changing the name, logo, redirect URIs or scopes clears the verified badge. enabled: false pauses every token.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • client_id
    stringpathrequired
    Partner app client id
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Request body

  • oauth_app
    objectrequired
  • oauth_app.name
    string
  • oauth_app.description
    string | null
  • oauth_app.logo_url
    string | null
  • oauth_app.homepage_url
    string | null
  • oauth_app.redirect_uris
    string[]
  • oauth_app.scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • oauth_app.is_agent
    boolean
  • oauth_app.enabled
    boolean

Response · 200 · object

  • client_id
    string
  • name
    string
  • description
    string | null
  • logo_url
    string | null
  • homepage_url
    string | null
  • redirect_uris
    string[]
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • verified
    boolean
  • is_agent
    boolean
  • company_id
    integer | null
  • status
    string
    One of: active, disabled, retired.
  • created_at
    string (date-time)
  • created_by_id
    integer | null
  • retired_at
    string (date-time) | null
  • token_endpoint_auth_method
    string

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 409Retired

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/oauth_apps/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "oauth_app": {}
}'
DELETE /rest/v1.0/companies/{company_id}/oauth_apps/{client_id}

Retire a partner app

Revokes every authorization in the same transaction. The client id stays reserved.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • client_id
    stringpathrequired
    Partner app client id
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Response · 204

No response body.

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/oauth_apps/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/service_accounts

List service accounts

Company admins only. Never returns secrets.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.

Response · 200 · object[]

  • id
    integer
  • name
    string
  • description
    string | null
  • owner_user_id
    integer
  • user_id
    integer
    The non-human user row the account acts as (appears as the actor in audit trails).
  • client_id
    string
  • is_agent
    boolean
    Agent accounts can only create and propose.
  • company_admin
    boolean
  • ip_allowlist
    string[]
  • status
    string
    One of: active, disabled.
  • disabled_at
    string (date-time) | null
  • last_used_at
    string (date-time) | null
  • created_at
    string (date-time)
  • created_by_id
    integer
  • credentials
    object[]
  • credentials[].id
    integer
  • credentials[].kind
    string
    One of: api_key, client_secret.
  • credentials[].label
    string
  • credentials[].prefix
    string
    Non-secret display hint (first 12 characters).
  • credentials[].scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • credentials[].status
    string
    One of: active, revoked, expired.
  • credentials[].expires_at
    string (date-time)
  • credentials[].created_at
    string (date-time)
  • credentials[].created_by_id
    integer
  • credentials[].revoked_at
    string (date-time) | null
  • credentials[].rotated_from_id
    integer | null
  • credentials[].last_used_at
    string (date-time) | null
  • credentials[].last_used_ip
    string | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/service_accounts

Create a service account

Creates a non-human account for an unattended integration. It cannot sign in to the app, cannot be a super admin and does not use a seat. Add credentials and project access next.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Request body

  • service_account
    objectrequired
  • service_account.name
    stringrequired
  • service_account.description
    string | null
  • service_account.owner_user_id
    integerrequired
    An active person in your company accountable for the account.
  • service_account.is_agent
    boolean
  • service_account.company_admin
    boolean
  • service_account.ip_allowlist
    string[]

Response · 201 · object

  • id
    integer
  • name
    string
  • description
    string | null
  • owner_user_id
    integer
  • user_id
    integer
    The non-human user row the account acts as (appears as the actor in audit trails).
  • client_id
    string
  • is_agent
    boolean
    Agent accounts can only create and propose.
  • company_admin
    boolean
  • ip_allowlist
    string[]
  • status
    string
    One of: active, disabled.
  • disabled_at
    string (date-time) | null
  • last_used_at
    string (date-time) | null
  • created_at
    string (date-time)
  • created_by_id
    integer
  • credentials
    object[]
  • credentials[].id
    integer
  • credentials[].kind
    string
    One of: api_key, client_secret.
  • credentials[].label
    string
  • credentials[].prefix
    string
    Non-secret display hint (first 12 characters).
  • credentials[].scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • credentials[].status
    string
    One of: active, revoked, expired.
  • credentials[].expires_at
    string (date-time)
  • credentials[].created_at
    string (date-time)
  • credentials[].created_by_id
    integer
  • credentials[].revoked_at
    string (date-time) | null
  • credentials[].rotated_from_id
    integer | null
  • credentials[].last_used_at
    string (date-time) | null
  • credentials[].last_used_ip
    string | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 422Invalid fields

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/service_accounts" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "service_account": {
    "name": "string",
    "owner_user_id": 1
  }
}'
GET /rest/v1.0/companies/{company_id}/service_accounts/{id}

Show a service account

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id

Response · 200 · object

  • id
    integer
  • name
    string
  • description
    string | null
  • owner_user_id
    integer
  • user_id
    integer
    The non-human user row the account acts as (appears as the actor in audit trails).
  • client_id
    string
  • is_agent
    boolean
    Agent accounts can only create and propose.
  • company_admin
    boolean
  • ip_allowlist
    string[]
  • status
    string
    One of: active, disabled.
  • disabled_at
    string (date-time) | null
  • last_used_at
    string (date-time) | null
  • created_at
    string (date-time)
  • created_by_id
    integer
  • credentials
    object[]
  • credentials[].id
    integer
  • credentials[].kind
    string
    One of: api_key, client_secret.
  • credentials[].label
    string
  • credentials[].prefix
    string
    Non-secret display hint (first 12 characters).
  • credentials[].scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • credentials[].status
    string
    One of: active, revoked, expired.
  • credentials[].expires_at
    string (date-time)
  • credentials[].created_at
    string (date-time)
  • credentials[].created_by_id
    integer
  • credentials[].revoked_at
    string (date-time) | null
  • credentials[].rotated_from_id
    integer | null
  • credentials[].last_used_at
    string (date-time) | null
  • credentials[].last_used_ip
    string | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/service_accounts/{id}

Update or disable a service account

disabled: true revokes every credential and access token immediately.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Request body

  • service_account
    objectrequired
  • service_account.name
    string
  • service_account.description
    string | null
  • service_account.owner_user_id
    integer
  • service_account.is_agent
    boolean
  • service_account.company_admin
    boolean
  • service_account.ip_allowlist
    string[]
  • service_account.disabled
    boolean
    true revokes every credential and token at once.

Response · 200 · object

  • id
    integer
  • name
    string
  • description
    string | null
  • owner_user_id
    integer
  • user_id
    integer
    The non-human user row the account acts as (appears as the actor in audit trails).
  • client_id
    string
  • is_agent
    boolean
    Agent accounts can only create and propose.
  • company_admin
    boolean
  • ip_allowlist
    string[]
  • status
    string
    One of: active, disabled.
  • disabled_at
    string (date-time) | null
  • last_used_at
    string (date-time) | null
  • created_at
    string (date-time)
  • created_by_id
    integer
  • credentials
    object[]
  • credentials[].id
    integer
  • credentials[].kind
    string
    One of: api_key, client_secret.
  • credentials[].label
    string
  • credentials[].prefix
    string
    Non-secret display hint (first 12 characters).
  • credentials[].scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • credentials[].status
    string
    One of: active, revoked, expired.
  • credentials[].expires_at
    string (date-time)
  • credentials[].created_at
    string (date-time)
  • credentials[].created_by_id
    integer
  • credentials[].revoked_at
    string (date-time) | null
  • credentials[].rotated_from_id
    integer | null
  • credentials[].last_used_at
    string (date-time) | null
  • credentials[].last_used_ip
    string | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 422Invalid fields

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "service_account": {}
}'
GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/calls

Service account audit log

Every API call the account made, newest first, including denied attempts. The next page cursor is in X-Next-Before.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • before
    stringquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    string
  • actor_type
    string
    One of: service_account, agent, partner_app.
  • actor_user_id
    integer
  • on_behalf_of_user_id
    integer | null
  • service_account_id
    integer | null
  • credential_ref
    string | null
  • client_id
    string | null
  • method
    string
  • route
    string | null
  • path
    string
  • action_class
    string | null
    One of: read, propose, approve, admin, null.
  • outcome
    string
    One of: allowed, denied.
  • denial_reason
    string | null
  • ip
    string | null
  • request_id
    string | null
  • created_at
    string (date-time)

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/calls" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials

List credentials

Never returns secrets.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id

Response · 200 · object[]

  • id
    integer
  • kind
    string
    One of: api_key, client_secret.
  • label
    string
  • prefix
    string
    Non-secret display hint (first 12 characters).
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • status
    string
    One of: active, revoked, expired.
  • expires_at
    string (date-time)
  • created_at
    string (date-time)
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • rotated_from_id
    integer | null
  • last_used_at
    string (date-time) | null
  • last_used_ip
    string | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/credentials" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials

Create a credential

Issues an API key (bearer) or an OAuth client secret (client_credentials). The secret is returned once. Scopes cannot exceed the scopes of the token making this call. At most 10 active credentials; expiry 1 to 365 days (default 90).

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • Idempotency-Key
    stringheader
    Not supported here: the response contains a one-time secret that is never stored, so sending this header returns 400. List credentials before retrying.

Request body

  • credential
    objectrequired
  • credential.kind
    string
    One of: api_key, client_secret.
  • credential.label
    stringrequired
  • credential.scopes
    string[]required
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • credential.expires_in_days
    integer

Response · 201 · object

  • id
    integer
  • kind
    string
    One of: api_key, client_secret.
  • label
    string
  • prefix
    string
    Non-secret display hint (first 12 characters).
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • status
    string
    One of: active, revoked, expired.
  • expires_at
    string (date-time)
  • created_at
    string (date-time)
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • rotated_from_id
    integer | null
  • last_used_at
    string (date-time) | null
  • last_used_ip
    string | null
  • secret
    string
    Shown once. API keys start with osc_sak_, client secrets with osc_scs_. Only a SHA-256 hash is stored.
  • client_id
    string | null
    For client secrets: the OAuth client_id (sa_<id>) to use with grant_type=client_credentials.

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 409Account disabled or credential limit reached
  • 422Invalid fields

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/credentials" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "credential": {
    "label": "string",
    "scopes": []
  }
}'
DELETE /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}

Revoke a credential

Stops the credential and every token minted from it now.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • credential_id
    integerpathrequired
    Credential id
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Response · 204

No response body.

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/credentials/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
POST /rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}/rotate

Rotate a credential

Issues a replacement with the same kind, label and scopes (secret shown once). The old secret keeps working for overlap_hours (0 to 168, default 24), then stops.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • credential_id
    integerpathrequired
    Credential id
  • Idempotency-Key
    stringheader
    Not supported here: the response contains a one-time secret that is never stored, so sending this header returns 400. List credentials before retrying.

Request body

  • rotation
    object
  • rotation.overlap_hours
    integer
  • rotation.expires_in_days
    integer

Response · 201 · object

  • id
    integer
  • kind
    string
    One of: api_key, client_secret.
  • label
    string
  • prefix
    string
    Non-secret display hint (first 12 characters).
  • scopes
    string[]
    API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
  • status
    string
    One of: active, revoked, expired.
  • expires_at
    string (date-time)
  • created_at
    string (date-time)
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • rotated_from_id
    integer | null
  • last_used_at
    string (date-time) | null
  • last_used_ip
    string | null
  • secret
    string
    Shown once. API keys start with osc_sak_, client secrets with osc_scs_. Only a SHA-256 hash is stored.
  • client_id
    string | null
    For client secrets: the OAuth client_id (sa_<id>) to use with grant_type=client_credentials.
  • previous
    object
  • previous.id
    integer
  • previous.expires_at
    string (date-time)

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company
  • 409Not active or already rotated

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/credentials/1/rotate" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "rotation": {}
}'
GET /rest/v1.0/companies/{company_id}/service_accounts/{id}/projects

List project access

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id

Response · 200 · object[]

  • project_id
    integer
  • project_name
    string
  • permission_template_id
    integer | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/projects" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PUT /rest/v1.0/companies/{company_id}/service_accounts/{id}/projects

Set project access

Adds the account to a project with a permission template, or removes it (permission_template_id null). Permission templates apply exactly as for a person.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Your company id; must match the caller's company.
  • id
    integerpathrequired
    Service account id
  • Idempotency-Key
    stringheader
    Optional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.

Request body

  • project_access
    objectrequired
  • project_access.project_id
    integerrequired
  • project_access.permission_template_id
    integer | nullrequired

Response · 200 · object

  • project_id
    integer
  • permission_template_id
    integer | null

Errors

  • 401Missing, invalid, expired or revoked credential
  • 403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)
  • 404Not found in your company

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/projects" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_access": {
    "project_id": 1,
    "permission_template_id": 1
  }
}'

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file