Identity
- GET
/rest/v1.0/auth/connected_appsList your connected apps - DELETE
/rest/v1.0/auth/connected_apps/{grant_id}Revoke one of your connected apps - GET
/rest/v1.0/companies/{company_id}/agent_activityNon-human API activity - GET
/rest/v1.0/companies/{company_id}/connected_appsList every app authorization in your company - DELETE
/rest/v1.0/companies/{company_id}/connected_apps/{grant_id}Revoke a person's app authorization - GET
/rest/v1.0/companies/{company_id}/oauth_appsList partner apps registered by your company - POST
/rest/v1.0/companies/{company_id}/oauth_appsRegister a partner app - GET
/rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Show a partner app - PATCH
/rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Update a partner app - DELETE
/rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Retire a partner app - GET
/rest/v1.0/companies/{company_id}/service_accountsList service accounts - POST
/rest/v1.0/companies/{company_id}/service_accountsCreate a service account - GET
/rest/v1.0/companies/{company_id}/service_accounts/{id}Show a service account - PATCH
/rest/v1.0/companies/{company_id}/service_accounts/{id}Update or disable a service account - GET
/rest/v1.0/companies/{company_id}/service_accounts/{id}/callsService account audit log - GET
/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsList credentials - POST
/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsCreate a credential - DELETE
/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}Revoke a credential - POST
/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}/rotateRotate a credential - GET
/rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsList project access - PUT
/rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsSet project access
/rest/v1.0/auth/connected_appsList your connected apps
Your own live authorizations. People only.
Parameters
- afterstringquery
Response · 200 · object[]
- idstring (uuid)
- user_idinteger
- user_namestring | null
- client_idstring
- client_namestring
- client_kindstringOne of: partner, mcp.
- verifiedboolean
- is_agentboolean
- resourcestring
- scopesstring[]
- created_atstring (date-time)
- expires_atstring (date-time)
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/auth/connected_apps" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/auth/connected_apps/{grant_id}Revoke one of your connected apps
People only.
Parameters
- grant_idstringpathrequiredAuthorization id (uuid)
- Idempotency-KeystringheaderOptional. 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 credential403Not 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
curl -X DELETE "https://app.os.construction/rest/v1.0/auth/connected_apps/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/agent_activityNon-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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- actor_typestringqueryOne of: service_account, agent, partner_app.
- outcomestringqueryOne of: allowed, denied.
- writesbooleanquery
- beforestringquery
- per_pageintegerquery
Response · 200 · object[]
- idstring
- actor_typestringOne of: service_account, agent, partner_app.
- actor_user_idinteger
- on_behalf_of_user_idinteger | null
- service_account_idinteger | null
- credential_refstring | null
- client_idstring | null
- methodstring
- routestring | null
- pathstring
- action_classstring | nullOne of: read, propose, approve, admin, null.
- outcomestringOne of: allowed, denied.
- denial_reasonstring | null
- ipstring | null
- request_idstring | null
- created_atstring (date-time)
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/agent_activity" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/connected_appsList every app authorization in your company
Live authorizations of partner apps and MCP clients held by your company's people.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
Response · 200 · object[]
- idstring (uuid)
- user_idinteger
- user_namestring | null
- client_idstring
- client_namestring
- client_kindstringOne of: partner, mcp.
- verifiedboolean
- is_agentboolean
- resourcestring
- scopesstring[]
- created_atstring (date-time)
- expires_atstring (date-time)
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connected_apps" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/connected_apps/{grant_id}Revoke a person's app authorization
Ends the authorization and all its tokens now.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- grant_idstringpathrequiredAuthorization id (uuid)
- Idempotency-KeystringheaderOptional. 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 credential403Not 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
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)"/rest/v1.0/companies/{company_id}/oauth_appsList partner apps registered by your company
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
Response · 200 · object[]
- client_idstring
- namestring
- descriptionstring | null
- logo_urlstring | null
- homepage_urlstring | null
- redirect_urisstring[]
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- verifiedboolean
- is_agentboolean
- company_idinteger | null
- statusstringOne of: active, disabled, retired.
- created_atstring (date-time)
- created_by_idinteger | null
- retired_atstring (date-time) | null
- token_endpoint_auth_methodstring
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/oauth_apps" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/oauth_appsRegister 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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- Idempotency-KeystringheaderOptional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.
Request body
- oauth_appobjectrequired
- oauth_app.namestringrequired
- oauth_app.descriptionstring | null
- oauth_app.logo_urlstring | null
- oauth_app.homepage_urlstring | null
- oauth_app.redirect_urisstring[]required
- oauth_app.scopesstring[]requiredAPI scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- oauth_app.is_agentboolean
Response · 201 · object
- client_idstring
- namestring
- descriptionstring | null
- logo_urlstring | null
- homepage_urlstring | null
- redirect_urisstring[]
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- verifiedboolean
- is_agentboolean
- company_idinteger | null
- statusstringOne of: active, disabled, retired.
- created_atstring (date-time)
- created_by_idinteger | null
- retired_atstring (date-time) | null
- token_endpoint_auth_methodstring
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company422Invalid fields
Example request
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": []
}
}'/rest/v1.0/companies/{company_id}/oauth_apps/{client_id}Show a partner app
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- client_idstringpathrequiredPartner app client id
Response · 200 · object
- client_idstring
- namestring
- descriptionstring | null
- logo_urlstring | null
- homepage_urlstring | null
- redirect_urisstring[]
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- verifiedboolean
- is_agentboolean
- company_idinteger | null
- statusstringOne of: active, disabled, retired.
- created_atstring (date-time)
- created_by_idinteger | null
- retired_atstring (date-time) | null
- token_endpoint_auth_methodstring
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/oauth_apps/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- client_idstringpathrequiredPartner app client id
- Idempotency-KeystringheaderOptional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.
Request body
- oauth_appobjectrequired
- oauth_app.namestring
- oauth_app.descriptionstring | null
- oauth_app.logo_urlstring | null
- oauth_app.homepage_urlstring | null
- oauth_app.redirect_urisstring[]
- oauth_app.scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- oauth_app.is_agentboolean
- oauth_app.enabledboolean
Response · 200 · object
- client_idstring
- namestring
- descriptionstring | null
- logo_urlstring | null
- homepage_urlstring | null
- redirect_urisstring[]
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- verifiedboolean
- is_agentboolean
- company_idinteger | null
- statusstringOne of: active, disabled, retired.
- created_atstring (date-time)
- created_by_idinteger | null
- retired_atstring (date-time) | null
- token_endpoint_auth_methodstring
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company409Retired
Example request
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": {}
}'/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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- client_idstringpathrequiredPartner app client id
- Idempotency-KeystringheaderOptional. 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 credential403Not 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
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)"/rest/v1.0/companies/{company_id}/service_accountsList service accounts
Company admins only. Never returns secrets.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
Response · 200 · object[]
- idinteger
- namestring
- descriptionstring | null
- owner_user_idinteger
- user_idintegerThe non-human user row the account acts as (appears as the actor in audit trails).
- client_idstring
- is_agentbooleanAgent accounts can only create and propose.
- company_adminboolean
- ip_allowliststring[]
- statusstringOne of: active, disabled.
- disabled_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_by_idinteger
- credentialsobject[]
- credentials[].idinteger
- credentials[].kindstringOne of: api_key, client_secret.
- credentials[].labelstring
- credentials[].prefixstringNon-secret display hint (first 12 characters).
- credentials[].scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- credentials[].statusstringOne of: active, revoked, expired.
- credentials[].expires_atstring (date-time)
- credentials[].created_atstring (date-time)
- credentials[].created_by_idinteger
- credentials[].revoked_atstring (date-time) | null
- credentials[].rotated_from_idinteger | null
- credentials[].last_used_atstring (date-time) | null
- credentials[].last_used_ipstring | null
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/service_accountsCreate 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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- Idempotency-KeystringheaderOptional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.
Request body
- service_accountobjectrequired
- service_account.namestringrequired
- service_account.descriptionstring | null
- service_account.owner_user_idintegerrequiredAn active person in your company accountable for the account.
- service_account.is_agentboolean
- service_account.company_adminboolean
- service_account.ip_allowliststring[]
Response · 201 · object
- idinteger
- namestring
- descriptionstring | null
- owner_user_idinteger
- user_idintegerThe non-human user row the account acts as (appears as the actor in audit trails).
- client_idstring
- is_agentbooleanAgent accounts can only create and propose.
- company_adminboolean
- ip_allowliststring[]
- statusstringOne of: active, disabled.
- disabled_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_by_idinteger
- credentialsobject[]
- credentials[].idinteger
- credentials[].kindstringOne of: api_key, client_secret.
- credentials[].labelstring
- credentials[].prefixstringNon-secret display hint (first 12 characters).
- credentials[].scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- credentials[].statusstringOne of: active, revoked, expired.
- credentials[].expires_atstring (date-time)
- credentials[].created_atstring (date-time)
- credentials[].created_by_idinteger
- credentials[].revoked_atstring (date-time) | null
- credentials[].rotated_from_idinteger | null
- credentials[].last_used_atstring (date-time) | null
- credentials[].last_used_ipstring | null
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company422Invalid fields
Example request
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
}
}'/rest/v1.0/companies/{company_id}/service_accounts/{id}Show a service account
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
Response · 200 · object
- idinteger
- namestring
- descriptionstring | null
- owner_user_idinteger
- user_idintegerThe non-human user row the account acts as (appears as the actor in audit trails).
- client_idstring
- is_agentbooleanAgent accounts can only create and propose.
- company_adminboolean
- ip_allowliststring[]
- statusstringOne of: active, disabled.
- disabled_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_by_idinteger
- credentialsobject[]
- credentials[].idinteger
- credentials[].kindstringOne of: api_key, client_secret.
- credentials[].labelstring
- credentials[].prefixstringNon-secret display hint (first 12 characters).
- credentials[].scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- credentials[].statusstringOne of: active, revoked, expired.
- credentials[].expires_atstring (date-time)
- credentials[].created_atstring (date-time)
- credentials[].created_by_idinteger
- credentials[].revoked_atstring (date-time) | null
- credentials[].rotated_from_idinteger | null
- credentials[].last_used_atstring (date-time) | null
- credentials[].last_used_ipstring | null
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/service_accounts/{id}Update or disable a service account
disabled: true revokes every credential and access token immediately.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- Idempotency-KeystringheaderOptional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.
Request body
- service_accountobjectrequired
- service_account.namestring
- service_account.descriptionstring | null
- service_account.owner_user_idinteger
- service_account.is_agentboolean
- service_account.company_adminboolean
- service_account.ip_allowliststring[]
- service_account.disabledbooleantrue revokes every credential and token at once.
Response · 200 · object
- idinteger
- namestring
- descriptionstring | null
- owner_user_idinteger
- user_idintegerThe non-human user row the account acts as (appears as the actor in audit trails).
- client_idstring
- is_agentbooleanAgent accounts can only create and propose.
- company_adminboolean
- ip_allowliststring[]
- statusstringOne of: active, disabled.
- disabled_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_by_idinteger
- credentialsobject[]
- credentials[].idinteger
- credentials[].kindstringOne of: api_key, client_secret.
- credentials[].labelstring
- credentials[].prefixstringNon-secret display hint (first 12 characters).
- credentials[].scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- credentials[].statusstringOne of: active, revoked, expired.
- credentials[].expires_atstring (date-time)
- credentials[].created_atstring (date-time)
- credentials[].created_by_idinteger
- credentials[].revoked_atstring (date-time) | null
- credentials[].rotated_from_idinteger | null
- credentials[].last_used_atstring (date-time) | null
- credentials[].last_used_ipstring | null
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company422Invalid fields
Example request
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": {}
}'/rest/v1.0/companies/{company_id}/service_accounts/{id}/callsService account audit log
Every API call the account made, newest first, including denied attempts. The next page cursor is in X-Next-Before.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- beforestringquery
- per_pageintegerquery
Response · 200 · object[]
- idstring
- actor_typestringOne of: service_account, agent, partner_app.
- actor_user_idinteger
- on_behalf_of_user_idinteger | null
- service_account_idinteger | null
- credential_refstring | null
- client_idstring | null
- methodstring
- routestring | null
- pathstring
- action_classstring | nullOne of: read, propose, approve, admin, null.
- outcomestringOne of: allowed, denied.
- denial_reasonstring | null
- ipstring | null
- request_idstring | null
- created_atstring (date-time)
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/calls" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsList credentials
Never returns secrets.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
Response · 200 · object[]
- idinteger
- kindstringOne of: api_key, client_secret.
- labelstring
- prefixstringNon-secret display hint (first 12 characters).
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- statusstringOne of: active, revoked, expired.
- expires_atstring (date-time)
- created_atstring (date-time)
- created_by_idinteger
- revoked_atstring (date-time) | null
- rotated_from_idinteger | null
- last_used_atstring (date-time) | null
- last_used_ipstring | null
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/credentials" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentialsCreate 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).
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- Idempotency-KeystringheaderNot 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
- credentialobjectrequired
- credential.kindstringOne of: api_key, client_secret.
- credential.labelstringrequired
- credential.scopesstring[]requiredAPI scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- credential.expires_in_daysinteger
Response · 201 · object
- idinteger
- kindstringOne of: api_key, client_secret.
- labelstring
- prefixstringNon-secret display hint (first 12 characters).
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- statusstringOne of: active, revoked, expired.
- expires_atstring (date-time)
- created_atstring (date-time)
- created_by_idinteger
- revoked_atstring (date-time) | null
- rotated_from_idinteger | null
- last_used_atstring (date-time) | null
- last_used_ipstring | null
- secretstringShown once. API keys start with osc_sak_, client secrets with osc_scs_. Only a SHA-256 hash is stored.
- client_idstring | nullFor client secrets: the OAuth client_id (sa_<id>) to use with grant_type=client_credentials.
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company409Account disabled or credential limit reached422Invalid fields
Example request
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": []
}
}'/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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- credential_idintegerpathrequiredCredential id
- Idempotency-KeystringheaderOptional. 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 credential403Not 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
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)"/rest/v1.0/companies/{company_id}/service_accounts/{id}/credentials/{credential_id}/rotateRotate 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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- credential_idintegerpathrequiredCredential id
- Idempotency-KeystringheaderNot 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
- rotationobject
- rotation.overlap_hoursinteger
- rotation.expires_in_daysinteger
Response · 201 · object
- idinteger
- kindstringOne of: api_key, client_secret.
- labelstring
- prefixstringNon-secret display hint (first 12 characters).
- scopesstring[]API scopes from the documented vocabulary (`<area>:read` or `<area>:write`).
- statusstringOne of: active, revoked, expired.
- expires_atstring (date-time)
- created_atstring (date-time)
- created_by_idinteger
- revoked_atstring (date-time) | null
- rotated_from_idinteger | null
- last_used_atstring (date-time) | null
- last_used_ipstring | null
- secretstringShown once. API keys start with osc_sak_, client secrets with osc_scs_. Only a SHA-256 hash is stored.
- client_idstring | nullFor client secrets: the OAuth client_id (sa_<id>) to use with grant_type=client_credentials.
- previousobject
- previous.idinteger
- previous.expires_atstring (date-time)
Errors
401Missing, invalid, expired or revoked credential403Not a company admin, missing scope, or a non-human caller (service accounts, agents and partner apps cannot manage credentials)404Not found in your company409Not active or already rotated
Example request
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": {}
}'/rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsList project access
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
Response · 200 · object[]
- project_idinteger
- project_namestring
- permission_template_idinteger | null
Errors
401Missing, invalid, expired or revoked credential403Not 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
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/service_accounts/1/projects" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/service_accounts/{id}/projectsSet 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.
Parameters
- company_idintegerpathrequiredYour company id; must match the caller's company.
- idintegerpathrequiredService account id
- Idempotency-KeystringheaderOptional. Repeating a request with the same key within 24 hours replays the first 2xx response instead of running the write again.
Request body
- project_accessobjectrequired
- project_access.project_idintegerrequired
- project_access.permission_template_idinteger | nullrequired
Response · 200 · object
- project_idinteger
- permission_template_idinteger | null
Errors
401Missing, invalid, expired or revoked credential403Not 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
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
}
}'