> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/admin-api/sources.md).

# Sources

The wearables and apps your Unified API users can connect, with their credentials and sign-in settings.

## List source types

> Lists every unified-api provider this environment can enable, described by its provider configuration and sorted by slug.\
> \
> \- Each row names the provider by the slug sources use, so a source joins its source type on \`provider\`.\
> \- Whether and how the environment has enabled a provider is on \`GET /environments/{dev\_id}/unified-api/sources\`.\
> \- A provider being retired is listed only for environments with access to it.\
> \- The list is complete in one response.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"SourceType":{"type":"object","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. apple_health. Sources and every other route name the provider by this value."},"display_name":{"type":"string","description":"The provider's name as shown to end users."},"icon":{"type":"string","description":"URL of the provider's icon."},"auth_type":{"type":"string","enum":["oauth2","oauth1","login","sdk"],"description":"How end users connect: oauth2 or oauth1 through the provider's consent screen, login with their provider username and password, or sdk through the mobile SDK on their device."},"setup":{"type":["string","null"],"description":"What setting the provider up involves, from its configuration, e.g. setup_not_required or api_keys_required. Null when the configuration does not say."},"data_types":{"type":"array","description":"The data types the provider can supply, as slugs.","items":{"type":"string"}},"deprecated":{"type":"boolean","description":"Whether the provider is being retired. A deprecated provider is listed only for environments with access to it."},"byo_supported":{"type":"boolean","description":"Whether users can connect through your own provider app instead of Terra's."},"custom_scopes_supported":{"type":"boolean","description":"Whether the provider has OAuth scopes you can switch on or off, through the source's scopes."},"customer_credentials_required":{"type":"boolean","description":"Whether you must add your own provider credentials before users can connect, because Terra has no app for this provider."},"custom_credentials_allowed":{"type":"boolean","description":"Whether you may set your own provider credentials."}},"required":["provider","display_name","icon","auth_type","setup","data_types","deprecated","byo_supported","custom_scopes_supported","customer_credentials_required","custom_credentials_allowed"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/source-types":{"get":{"operationId":"listSourceTypes","tags":["sources"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SourceType"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"List source types","description":"Lists every unified-api provider this environment can enable, described by its provider configuration and sorted by slug.\n\n- Each row names the provider by the slug sources use, so a source joins its source type on `provider`.\n- Whether and how the environment has enabled a provider is on `GET /environments/{dev_id}/unified-api/sources`.\n- A provider being retired is listed only for environments with access to it.\n- The list is complete in one response.","parameters":[{"$ref":"#/components/parameters/DevId"}]}}}}
```

## List sources

> Lists the unified-api providers enabled in this environment, with each one's slug, whether it is \`active\`, its auth redirect URL, and whether users connect through Terra's OAuth app or your own by default.\
> \
> \- A paused provider is listed with \`active: false\`. Deprecated providers are listed; internal providers are not.\
> \- Every listed provider can be addressed under \`/environments/{dev\_id}/unified-api/sources/{provider}\`.\
> \- Credentials and custom scopes are on their own sub-resources; capabilities and deprecation are on the source type.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"Source":{"type":"object","description":"A provider enabled for an environment, as every sources operation returns it.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. garmin or apple_health."},"active":{"type":"boolean","description":"Whether the provider accepts new connections. A paused provider is false and stays listed with its credentials and scopes."},"auth_redirect_url":{"type":["string","null"],"description":"Where the provider sends users back after they authorize, or null when it has none."},"auth_variant":{"type":"string","enum":["standard","byo"],"description":"How users connect by default: standard through Terra's OAuth app, or byo through your own."}},"required":["provider","active","auth_redirect_url","auth_variant"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/sources":{"get":{"operationId":"listSources","tags":["sources"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List sources","description":"Lists the unified-api providers enabled in this environment, with each one's slug, whether it is `active`, its auth redirect URL, and whether users connect through Terra's OAuth app or your own by default.\n\n- A paused provider is listed with `active: false`. Deprecated providers are listed; internal providers are not.\n- Every listed provider can be addressed under `/environments/{dev_id}/unified-api/sources/{provider}`.\n- Credentials and custom scopes are on their own sub-resources; capabilities and deprecation are on the source type.","parameters":[{"$ref":"#/components/parameters/DevId"}]}}}}
```

## Enable several providers

> Enables several providers in one transaction, so either every provider is enabled or none is, and returns each provider's source in request order.\
> \
> \- Each is enabled as \`PUT /environments/{dev\_id}/unified-api/sources/{provider}\` does it: no credentials, no scopes, an already-enabled one is left as it is and a paused one is resumed, so a repeat call is safe.\
> \- Every provider is checked before anything is written.\
> \- When every provider is already active, the preview's \`would\` is \`noop\` and nothing is written.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"BatchEnabledSources":{"type":"object","properties":{"data":{"type":"array","description":"One entry per requested provider, in request order.","items":{"$ref":"#/components/schemas/Source"}}},"required":["data"]},"Source":{"type":"object","description":"A provider enabled for an environment, as every sources operation returns it.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. garmin or apple_health."},"active":{"type":"boolean","description":"Whether the provider accepts new connections. A paused provider is false and stays listed with its credentials and scopes."},"auth_redirect_url":{"type":["string","null"],"description":"Where the provider sends users back after they authorize, or null when it has none."},"auth_variant":{"type":"string","enum":["standard","byo"],"description":"How users connect by default: standard through Terra's OAuth app, or byo through your own."}},"required":["provider","active","auth_redirect_url","auth_variant"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]},"BatchEnableSourcesRequest":{"type":"object","properties":{"providers":{"type":"array","description":"The providers to enable, as slugs, e.g. garmin: at least 1 and at most 100, each listed once. An unrecognised or repeated provider is a 400, and one in private preview for which this environment has no preview is a 422, each naming its position, and then nothing is enabled.","items":{"type":"string"},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["providers"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/batch-enable":{"post":{"operationId":"batchEnableSources","tags":["sources"],"responses":{"200":{"description":"Enabled (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/BatchEnabledSources"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Enable several providers","description":"Enables several providers in one transaction, so either every provider is enabled or none is, and returns each provider's source in request order.\n\n- Each is enabled as `PUT /environments/{dev_id}/unified-api/sources/{provider}` does it: no credentials, no scopes, an already-enabled one is left as it is and a paused one is resumed, so a repeat call is safe.\n- Every provider is checked before anything is written.\n- When every provider is already active, the preview's `would` is `noop` and nothing is written.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnableSourcesRequest"}}}}}}}}
```

## Disable several providers

> Disables several providers in one transaction, so either every provider is disabled or none is.\
> \
> \- Each is disabled as \`DELETE /environments/{dev\_id}/unified-api/sources/{provider}\` does it: nothing is collected from it while it is off, and enabling it again does not backfill the gap.\
> \- Every provider is checked before anything is written.\
> \- \`POST /environments/{dev\_id}/unified-api/sources/batch-enable\` is the inverse.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]},"BatchDisableSourcesRequest":{"type":"object","properties":{"providers":{"type":"array","description":"The providers to disable, as slugs, e.g. garmin: at least 1 and at most 100, each listed once. An unrecognised or repeated provider is a 400, and one that is not enabled is a 404, each naming its position, and then nothing is disabled.","items":{"type":"string"},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["providers"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/batch-disable":{"post":{"operationId":"batchDisableSources","tags":["sources"],"responses":{"200":{"description":"Dry-run preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"204":{"description":"Disabled."},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Disable several providers","description":"Disables several providers in one transaction, so either every provider is disabled or none is.\n\n- Each is disabled as `DELETE /environments/{dev_id}/unified-api/sources/{provider}` does it: nothing is collected from it while it is off, and enabling it again does not backfill the gap.\n- Every provider is checked before anything is written.\n- `POST /environments/{dev_id}/unified-api/sources/batch-enable` is the inverse.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDisableSourcesRequest"}}}}}}}}
```

## Enable a provider (idempotent)

> Enables a provider in this environment and returns its source.\
> \
> \- No credentials or scopes are configured, so until custom credentials are set end users authorize against Terra's own OAuth app, which \`terra\_owned\` reports on the credentials read.\
> \- A paused provider is resumed, and one that was disabled comes back with its credentials.\
> \- A repeat call is not an error: its preview's \`would\` is \`noop\`, and it writes nothing.\
> \- A deprecated provider needs its private preview on this environment, or the call is a 422, in a preview too.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"Source":{"type":"object","description":"A provider enabled for an environment, as every sources operation returns it.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. garmin or apple_health."},"active":{"type":"boolean","description":"Whether the provider accepts new connections. A paused provider is false and stays listed with its credentials and scopes."},"auth_redirect_url":{"type":["string","null"],"description":"Where the provider sends users back after they authorize, or null when it has none."},"auth_variant":{"type":"string","enum":["standard","byo"],"description":"How users connect by default: standard through Terra's OAuth app, or byo through your own."}},"required":["provider","active","auth_redirect_url","auth_variant"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}":{"put":{"operationId":"enableSource","tags":["sources"],"responses":{"200":{"description":"Enabled (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/Source"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Enable a provider (idempotent)","description":"Enables a provider in this environment and returns its source.\n\n- No credentials or scopes are configured, so until custom credentials are set end users authorize against Terra's own OAuth app, which `terra_owned` reports on the credentials read.\n- A paused provider is resumed, and one that was disabled comes back with its credentials.\n- A repeat call is not an error: its preview's `would` is `noop`, and it writes nothing.\n- A deprecated provider needs its private preview on this environment, or the call is a 422, in a preview too.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}]}}}}
```

## Disable a provider

> Disables a provider, taking it out of this environment's enabled set.\
> \
> \- Nothing is collected from it while it is off, and enabling it again does not backfill the gap.\
> \- \`PUT\` on this path is the inverse.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}":{"delete":{"operationId":"disableSource","tags":["sources"],"responses":{"200":{"description":"Dry-run preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"204":{"description":"Disabled."},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Disable a provider","description":"Disables a provider, taking it out of this environment's enabled set.\n\n- Nothing is collected from it while it is off, and enabling it again does not backfill the gap.\n- `PUT` on this path is the inverse.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}]}}}}
```

## Update a provider

> Pauses or resumes an enabled provider, or changes how its users connect by default.\
> \
> \- Pausing refuses new connections but keeps the provider listed with its credentials, scopes and existing connections. \`DELETE\` on this path removes it instead.\
> \- \`auth\_variant: byo\` needs \`byo\_supported\` on the source type, or is a 422.\
> \- Send at least one field.\
> \- A deprecated provider can always be paused, but resuming it or changing its auth variant needs its private preview on this environment, or the call is a 422.\
> \- When nothing would change, the preview's \`would\` is \`noop\` and nothing is written.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"Source":{"type":"object","description":"A provider enabled for an environment, as every sources operation returns it.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. garmin or apple_health."},"active":{"type":"boolean","description":"Whether the provider accepts new connections. A paused provider is false and stays listed with its credentials and scopes."},"auth_redirect_url":{"type":["string","null"],"description":"Where the provider sends users back after they authorize, or null when it has none."},"auth_variant":{"type":"string","enum":["standard","byo"],"description":"How users connect by default: standard through Terra's OAuth app, or byo through your own."}},"required":["provider","active","auth_redirect_url","auth_variant"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]},"PatchSourceRequest":{"type":"object","properties":{"active":{"type":"boolean","description":"false pauses the provider and true resumes it. Omitted leaves it as it is."},"auth_variant":{"type":"string","enum":["standard","byo"],"description":"standard connects users through Terra's OAuth app and byo through your own, which the provider must support. Omitted leaves it as it is."}}}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}":{"patch":{"operationId":"updateSource","tags":["sources"],"responses":{"200":{"description":"Updated (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/Source"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Update a provider","description":"Pauses or resumes an enabled provider, or changes how its users connect by default.\n\n- Pausing refuses new connections but keeps the provider listed with its credentials, scopes and existing connections. `DELETE` on this path removes it instead.\n- `auth_variant: byo` needs `byo_supported` on the source type, or is a 422.\n- Send at least one field.\n- A deprecated provider can always be paused, but resuming it or changing its auth variant needs its private preview on this environment, or the call is a 422.\n- When nothing would change, the preview's `would` is `noop` and nothing is written.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400. A provider that is not enabled is a 404: enable it first with the PUT on this path."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSourceRequest"}}}}}}}}
```

## Provider OAuth credentials (masked)

> Returns this environment's own OAuth app for the provider, if it has one: the client id with the secret masked to its last digits, the redirect URL, the sandbox flag, the OAuth version and whether a webhook verification secret is stored.\
> \
> \- \`credential\` is null when none is set or when the provider runs on Terra's own app, which \`terra\_owned\` reports.\
> \- The OAuth version is null for providers that do not sign in with OAuth.\
> \- A paused provider keeps its credentials and reports them here.\
> \- Secrets are write-only and are never readable here.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"ProviderCredentials":{"type":"object","properties":{"provider":{"type":"string"},"has_credentials":{"type":"boolean","description":"Whether this environment has its own OAuth app for the provider."},"terra_owned":{"type":"boolean","description":"Whether the provider runs on Terra's own OAuth app."},"credential":{"description":"Your own OAuth app, with its secret masked. Null when none is set or Terra's app is in use.","oneOf":[{"$ref":"#/components/schemas/ProviderCredentialMaterial"},{"type":"null"}]}},"required":["provider","has_credentials","terra_owned","credential"]},"ProviderCredentialMaterial":{"type":"object","properties":{"provider_client_id":{"type":"string"},"provider_client_secret_masked":{"type":["string","null"],"description":"The client secret with all but its last four characters masked. Null when secret_ref reads it from a secret store."},"redirect_url":{"type":["string","null"],"description":"The OAuth redirect URL users return to. Null when the provider has none."},"sandbox":{"type":"boolean","description":"Whether auth runs against the provider's sandbox."},"oauth_version":{"type":["string","null"],"enum":["1","2",null],"description":"The OAuth version the stored app uses. Null for providers that do not sign in with OAuth."},"has_verification_secret":{"type":"boolean","description":"Whether a webhook verification secret is stored. The secret itself is never returned."},"secret_ref":{"description":"Where the client secret is read from in a secret store, or null when Terra stores it.","oneOf":[{"$ref":"#/components/schemas/ProviderSecretRefDetails"},{"type":"null"}]}},"required":["provider_client_id","provider_client_secret_masked","redirect_url","sandbox","oauth_version","has_verification_secret","secret_ref"]},"ProviderSecretRefDetails":{"type":"object","description":"Where a provider secret is read from in a secret store.","properties":{"store":{"type":"string","description":"The secret store the secret is read from, as its type: aws or gcp."},"config":{"$ref":"#/components/schemas/SecretRefConfigView"},"client_secret_field":{"type":["string","null"],"description":"The key the client secret is read from. Null when the whole value is the secret."},"client_id_field":{"type":["string","null"],"description":"The key the client_id is read from. Null when the client_id is stored with Terra."}},"required":["store","config","client_secret_field","client_id_field"]},"SecretRefConfigView":{"description":"Where in the store the secret is, by store type.","anyOf":[{"$ref":"#/components/schemas/AwsSecretRefConfigView"},{"$ref":"#/components/schemas/GcpSecretRefConfigView"}]},"AwsSecretRefConfigView":{"type":"object","properties":{"role_arn":{"type":"string","description":"The IAM role Terra assumes."},"secret_arn":{"type":"string","description":"The Secrets Manager secret, SSM parameter or S3 object holding the secret."}},"required":["role_arn","secret_arn"]},"GcpSecretRefConfigView":{"type":"object","properties":{"secret_name":{"type":"string","description":"The Secret Manager secret holding the secret, as projects/{project}/secrets/{secret}, with /versions/{version} when pinned."}},"required":["secret_name"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/credentials":{"get":{"operationId":"getSourceCredentials","tags":["sources"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCredentials"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Provider OAuth credentials (masked)","description":"Returns this environment's own OAuth app for the provider, if it has one: the client id with the secret masked to its last digits, the redirect URL, the sandbox flag, the OAuth version and whether a webhook verification secret is stored.\n\n- `credential` is null when none is set or when the provider runs on Terra's own app, which `terra_owned` reports.\n- The OAuth version is null for providers that do not sign in with OAuth.\n- A paused provider keeps its credentials and reports them here.\n- Secrets are write-only and are never readable here.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400."}]}}}}
```

## Set custom sign-in settings for a wearable or app

> Replaces this environment's own OAuth credentials for the provider, so auth runs against your app. Idempotent.\
> \
> \- An omitted \`redirect\_url\`, verification secret or \`sandbox\` goes back to its default; \`PATCH\` on this path keeps unsent fields.\
> \- A \`redirect\_url\` must be on a Terra domain or on a custom domain set up for this provider in this or another of your environments within the token's audience, or the call is a 400; a 503 means the custom domain could not be checked.\
> \- With \`secret\_ref\`, Terra test-reads the store before saving: a setup it cannot read is a 400 saying which step failed, an unreachable store is a 503, and a source or deployment without the option is a 422.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}},"schemas":{"ProviderCredentialWrite":{"type":"object","properties":{"client_id":{"type":"string","description":"The customer's OAuth client id for this provider. Required unless secret_ref.client_id_field reads it."},"client_secret":{"type":"string","description":"The customer's OAuth client secret (write-only; reads are masked). Required unless secret_ref is sent."},"secret_ref":{"description":"Read the client secret from a secret store you own instead of sending it. Not allowed with client_secret; null keeps the secret with Terra.","oneOf":[{"$ref":"#/components/schemas/ProviderSecretRef"},{"type":"null"}]},"redirect_url":{"type":"string","description":"Override the OAuth redirect URL (defaults to the provider default). Its host must be Terra's or a custom domain set up for this provider."},"verification_secret":{"type":"string","description":"Optional webhook verification secret. Not accepted for an OAuth 1.0 app."},"sandbox":{"type":"boolean","description":"Use the provider's sandbox environment. Not accepted for an OAuth 1.0 app."}},"oneOf":[{"required":["client_id","client_secret"],"not":{"properties":{"secret_ref":{"type":"object"}},"required":["secret_ref"]}},{"properties":{"secret_ref":{"type":"object","not":{"required":["client_id_field"]}}},"required":["client_id","secret_ref"],"not":{"required":["client_secret"]}},{"properties":{"secret_ref":{"type":"object","required":["client_id_field"]}},"required":["secret_ref"],"not":{"anyOf":[{"required":["client_secret"]},{"required":["client_id"]}]}}]},"ProviderSecretRef":{"type":"object","description":"A provider secret kept in a secret store you own, which Terra reads instead of storing it. Only the sources the store lists accept it.","properties":{"store":{"type":"string","description":"The secret store to read from: aws or gcp. An unrecognised store is a 400.","minLength":1},"config":{"description":"Where in the store the secret is.","$ref":"#/components/schemas/SecretRefConfig"},"client_secret_field":{"type":"string","description":"The key to read the client secret from when the secret is a JSON object or an env file. Omit to use the whole value.","minLength":1},"client_id_field":{"type":"string","description":"The key to read the client_id from in the same JSON object or env file. Omit to send client_id yourself.","minLength":1}},"required":["store","config"],"additionalProperties":false},"SecretRefConfig":{"description":"Where in the store the secret is, by store type.","anyOf":[{"$ref":"#/components/schemas/AwsSecretRefConfig"},{"$ref":"#/components/schemas/GcpSecretRefConfig"}]},"AwsSecretRefConfig":{"type":"object","properties":{"role_arn":{"type":"string","description":"The IAM role Terra assumes, whose trust policy requires the External ID Terra gives your account.","minLength":1},"secret_arn":{"type":"string","description":"The Secrets Manager secret, SSM parameter or S3 object holding the secret.","minLength":1}},"required":["role_arn","secret_arn"],"additionalProperties":false},"GcpSecretRefConfig":{"type":"object","properties":{"secret_name":{"type":"string","description":"The Secret Manager secret, as projects/{project}/secrets/{secret}. Add /versions/{version} to pin one; otherwise Terra reads the latest. The secret must carry the label your secret store type names, set to your External ID.","minLength":1}},"required":["secret_name"],"additionalProperties":false},"ProviderCredentials":{"type":"object","properties":{"provider":{"type":"string"},"has_credentials":{"type":"boolean","description":"Whether this environment has its own OAuth app for the provider."},"terra_owned":{"type":"boolean","description":"Whether the provider runs on Terra's own OAuth app."},"credential":{"description":"Your own OAuth app, with its secret masked. Null when none is set or Terra's app is in use.","oneOf":[{"$ref":"#/components/schemas/ProviderCredentialMaterial"},{"type":"null"}]}},"required":["provider","has_credentials","terra_owned","credential"]},"ProviderCredentialMaterial":{"type":"object","properties":{"provider_client_id":{"type":"string"},"provider_client_secret_masked":{"type":["string","null"],"description":"The client secret with all but its last four characters masked. Null when secret_ref reads it from a secret store."},"redirect_url":{"type":["string","null"],"description":"The OAuth redirect URL users return to. Null when the provider has none."},"sandbox":{"type":"boolean","description":"Whether auth runs against the provider's sandbox."},"oauth_version":{"type":["string","null"],"enum":["1","2",null],"description":"The OAuth version the stored app uses. Null for providers that do not sign in with OAuth."},"has_verification_secret":{"type":"boolean","description":"Whether a webhook verification secret is stored. The secret itself is never returned."},"secret_ref":{"description":"Where the client secret is read from in a secret store, or null when Terra stores it.","oneOf":[{"$ref":"#/components/schemas/ProviderSecretRefDetails"},{"type":"null"}]}},"required":["provider_client_id","provider_client_secret_masked","redirect_url","sandbox","oauth_version","has_verification_secret","secret_ref"]},"ProviderSecretRefDetails":{"type":"object","description":"Where a provider secret is read from in a secret store.","properties":{"store":{"type":"string","description":"The secret store the secret is read from, as its type: aws or gcp."},"config":{"$ref":"#/components/schemas/SecretRefConfigView"},"client_secret_field":{"type":["string","null"],"description":"The key the client secret is read from. Null when the whole value is the secret."},"client_id_field":{"type":["string","null"],"description":"The key the client_id is read from. Null when the client_id is stored with Terra."}},"required":["store","config","client_secret_field","client_id_field"]},"SecretRefConfigView":{"description":"Where in the store the secret is, by store type.","anyOf":[{"$ref":"#/components/schemas/AwsSecretRefConfigView"},{"$ref":"#/components/schemas/GcpSecretRefConfigView"}]},"AwsSecretRefConfigView":{"type":"object","properties":{"role_arn":{"type":"string","description":"The IAM role Terra assumes."},"secret_arn":{"type":"string","description":"The Secrets Manager secret, SSM parameter or S3 object holding the secret."}},"required":["role_arn","secret_arn"]},"GcpSecretRefConfigView":{"type":"object","properties":{"secret_name":{"type":"string","description":"The Secret Manager secret holding the secret, as projects/{project}/secrets/{secret}, with /versions/{version} when pinned."}},"required":["secret_name"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/credentials":{"put":{"operationId":"setSourceCredentials","tags":["sources"],"summary":"Set custom sign-in settings for a wearable or app","description":"Replaces this environment's own OAuth credentials for the provider, so auth runs against your app. Idempotent.\n\n- An omitted `redirect_url`, verification secret or `sandbox` goes back to its default; `PATCH` on this path keeps unsent fields.\n- A `redirect_url` must be on a Terra domain or on a custom domain set up for this provider in this or another of your environments within the token's audience, or the call is a 400; a 503 means the custom domain could not be checked.\n- With `secret_ref`, Terra test-reads the store before saving: a setup it cannot read is a 400 saying which step failed, an unreachable store is a 503, and a source or deployment without the option is a 422.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCredentialWrite"}}}},"responses":{"200":{"description":"Stored (or DryRunResult when ?dry_run=true; the client secret is masked in both).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/ProviderCredentials"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```

## Update custom sign-in settings for a wearable or app

> Changes the sent fields of this environment's own OAuth credentials for the provider and keeps every other stored value.\
> \
> \- Send at least one field. An empty \`client\_secret\` or \`verification\_secret\` is a 400; omit it to keep the stored value.\
> \- The merged credential passes every check \`PUT\` on this path runs, including, for Garmin, a check against Garmin with the stored secret; the redirect host check runs when \`redirect\_url\` is sent.\
> \- A credential read from a secret store keeps reading it there when neither \`secret\_ref\` nor \`client\_secret\` is sent.\
> \- When the merged credential equals the stored one, nothing is written.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}},"schemas":{"ProviderCredentialPatch":{"type":"object","properties":{"client_id":{"type":"string","description":"The customer's OAuth client id. Omit to keep the stored one."},"client_secret":{"type":"string","description":"A new OAuth client secret (write-only). Omit to keep the stored one; an empty string is rejected."},"redirect_url":{"type":["string","null"],"description":"A new OAuth redirect URL, whose host must be Terra's or a custom domain set up for this provider. Null resets it to the provider default; omit to keep it."},"verification_secret":{"type":["string","null"],"description":"A new webhook verification secret (write-only). Null clears it; omit to keep it. Not accepted for an OAuth 1.0 app."},"sandbox":{"type":"boolean","description":"Use the provider's sandbox environment. Omit to keep the stored setting. Not accepted for an OAuth 1.0 app."},"secret_ref":{"description":"Read the client secret from a secret store you own from now on. Not allowed with client_secret. Null, sent with client_secret, moves the secret back to Terra, as client_secret alone does.","oneOf":[{"$ref":"#/components/schemas/ProviderSecretRef"},{"type":"null"}]}},"not":{"anyOf":[{"properties":{"secret_ref":{"type":"object"}},"required":["client_secret","secret_ref"]},{"properties":{"secret_ref":{"type":"object","required":["client_id_field"]}},"required":["client_id","secret_ref"]},{"properties":{"secret_ref":{"type":"null"}},"required":["secret_ref"],"not":{"required":["client_secret"]}}]},"minProperties":1},"ProviderSecretRef":{"type":"object","description":"A provider secret kept in a secret store you own, which Terra reads instead of storing it. Only the sources the store lists accept it.","properties":{"store":{"type":"string","description":"The secret store to read from: aws or gcp. An unrecognised store is a 400.","minLength":1},"config":{"description":"Where in the store the secret is.","$ref":"#/components/schemas/SecretRefConfig"},"client_secret_field":{"type":"string","description":"The key to read the client secret from when the secret is a JSON object or an env file. Omit to use the whole value.","minLength":1},"client_id_field":{"type":"string","description":"The key to read the client_id from in the same JSON object or env file. Omit to send client_id yourself.","minLength":1}},"required":["store","config"],"additionalProperties":false},"SecretRefConfig":{"description":"Where in the store the secret is, by store type.","anyOf":[{"$ref":"#/components/schemas/AwsSecretRefConfig"},{"$ref":"#/components/schemas/GcpSecretRefConfig"}]},"AwsSecretRefConfig":{"type":"object","properties":{"role_arn":{"type":"string","description":"The IAM role Terra assumes, whose trust policy requires the External ID Terra gives your account.","minLength":1},"secret_arn":{"type":"string","description":"The Secrets Manager secret, SSM parameter or S3 object holding the secret.","minLength":1}},"required":["role_arn","secret_arn"],"additionalProperties":false},"GcpSecretRefConfig":{"type":"object","properties":{"secret_name":{"type":"string","description":"The Secret Manager secret, as projects/{project}/secrets/{secret}. Add /versions/{version} to pin one; otherwise Terra reads the latest. The secret must carry the label your secret store type names, set to your External ID.","minLength":1}},"required":["secret_name"],"additionalProperties":false},"ProviderCredentials":{"type":"object","properties":{"provider":{"type":"string"},"has_credentials":{"type":"boolean","description":"Whether this environment has its own OAuth app for the provider."},"terra_owned":{"type":"boolean","description":"Whether the provider runs on Terra's own OAuth app."},"credential":{"description":"Your own OAuth app, with its secret masked. Null when none is set or Terra's app is in use.","oneOf":[{"$ref":"#/components/schemas/ProviderCredentialMaterial"},{"type":"null"}]}},"required":["provider","has_credentials","terra_owned","credential"]},"ProviderCredentialMaterial":{"type":"object","properties":{"provider_client_id":{"type":"string"},"provider_client_secret_masked":{"type":["string","null"],"description":"The client secret with all but its last four characters masked. Null when secret_ref reads it from a secret store."},"redirect_url":{"type":["string","null"],"description":"The OAuth redirect URL users return to. Null when the provider has none."},"sandbox":{"type":"boolean","description":"Whether auth runs against the provider's sandbox."},"oauth_version":{"type":["string","null"],"enum":["1","2",null],"description":"The OAuth version the stored app uses. Null for providers that do not sign in with OAuth."},"has_verification_secret":{"type":"boolean","description":"Whether a webhook verification secret is stored. The secret itself is never returned."},"secret_ref":{"description":"Where the client secret is read from in a secret store, or null when Terra stores it.","oneOf":[{"$ref":"#/components/schemas/ProviderSecretRefDetails"},{"type":"null"}]}},"required":["provider_client_id","provider_client_secret_masked","redirect_url","sandbox","oauth_version","has_verification_secret","secret_ref"]},"ProviderSecretRefDetails":{"type":"object","description":"Where a provider secret is read from in a secret store.","properties":{"store":{"type":"string","description":"The secret store the secret is read from, as its type: aws or gcp."},"config":{"$ref":"#/components/schemas/SecretRefConfigView"},"client_secret_field":{"type":["string","null"],"description":"The key the client secret is read from. Null when the whole value is the secret."},"client_id_field":{"type":["string","null"],"description":"The key the client_id is read from. Null when the client_id is stored with Terra."}},"required":["store","config","client_secret_field","client_id_field"]},"SecretRefConfigView":{"description":"Where in the store the secret is, by store type.","anyOf":[{"$ref":"#/components/schemas/AwsSecretRefConfigView"},{"$ref":"#/components/schemas/GcpSecretRefConfigView"}]},"AwsSecretRefConfigView":{"type":"object","properties":{"role_arn":{"type":"string","description":"The IAM role Terra assumes."},"secret_arn":{"type":"string","description":"The Secrets Manager secret, SSM parameter or S3 object holding the secret."}},"required":["role_arn","secret_arn"]},"GcpSecretRefConfigView":{"type":"object","properties":{"secret_name":{"type":"string","description":"The Secret Manager secret holding the secret, as projects/{project}/secrets/{secret}, with /versions/{version} when pinned."}},"required":["secret_name"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/credentials":{"patch":{"operationId":"updateSourceCredentials","tags":["sources"],"summary":"Update custom sign-in settings for a wearable or app","description":"Changes the sent fields of this environment's own OAuth credentials for the provider and keeps every other stored value.\n\n- Send at least one field. An empty `client_secret` or `verification_secret` is a 400; omit it to keep the stored value.\n- The merged credential passes every check `PUT` on this path runs, including, for Garmin, a check against Garmin with the stored secret; the redirect host check runs when `redirect_url` is sent.\n- A credential read from a secret store keeps reading it there when neither `secret_ref` nor `client_secret` is sent.\n- When the merged credential equals the stored one, nothing is written.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400. A provider without your own credentials is a 404; set them with the PUT on this path first."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCredentialPatch"}}}},"responses":{"200":{"description":"Updated (or DryRunResult when ?dry_run=true; the client secret is masked in both).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/ProviderCredentials"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```

## A provider's custom domain

> Returns the subdomain this environment set up for the provider's OAuth redirect (and, for Garmin and Strava, its webhooks): the A record to publish, the certificate's state, and whether the edge already serves it.\
> \
> \- The domain is live when \`state\` is \`ACTIVE\` and \`serving\` is true. \`FAILED\`, or a reason such as \`CAA\`, names what to fix.\
> \- With none of its own, a domain another of your environments within the token's audience set up, which this one's stored redirect is on, is returned with \`shared: true\`. No domain is a 404.\
> \- Each call looks the hostname up in DNS and makes a TLS request to it, so poll every 5 seconds or slower.\
> \- 503 \`service\_unavailable\`: custom domains are not available on this deployment; 503 \`dependency\_failed\`: the certificate service did not answer.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"SourceDomain":{"type":"object","description":"A subdomain you own that a provider's OAuth redirect, and for some providers its webhooks, run through.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. whoop."},"hostname":{"type":"string","description":"The subdomain, lower-cased."},"state":{"type":"string","enum":["PROVISIONING","ACTIVE","FAILED"],"description":"PROVISIONING until the certificate is issued, then ACTIVE. FAILED needs the DNS record or CAA fixed; reason and detail say which."},"reason":{"type":["string","null"],"description":"Why issuance is failing, as a machine-readable reason such as CAA. Null while nothing is wrong."},"detail":{"type":["string","null"],"description":"What to fix, in words. Null while nothing is wrong."},"dns_record":{"description":"The DNS record to publish at your DNS provider.","$ref":"#/components/schemas/SourceDomainDnsRecord"},"resolved_ip":{"type":["string","null"],"description":"The address the hostname resolves to now, preferring one of Terra's edge addresses. Null when it does not resolve."},"resolved_ips":{"type":"array","description":"Every address the hostname publishes, both families. Empty when it does not resolve.","items":{"type":"string"}},"serving":{"type":"boolean","description":"Whether Terra's edge answers TLS for the hostname. Only true once ACTIVE, and only then is the domain live."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the certificate expires, as an ISO 8601 timestamp. Null until it is first issued."},"shared":{"type":"boolean","description":"Whether another of your environments holds the certificate and this one reuses it."},"redirect_served":{"type":"boolean","description":"Whether this environment's stored redirect for the provider is on this hostname."}},"required":["provider","hostname","state","reason","detail","dns_record","resolved_ip","resolved_ips","serving","expires_at","shared","redirect_served"]},"SourceDomainDnsRecord":{"type":"object","description":"The single record that points a subdomain at Terra's edge.","properties":{"type":{"type":"string","enum":["A"]},"name":{"type":"string","description":"The record name, which is the hostname."},"value":{"type":"string","description":"The address to point it at."}},"required":["type","name","value"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/domain":{"get":{"operationId":"getSourceDomain","tags":["sources"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDomain"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"A provider's custom domain","description":"Returns the subdomain this environment set up for the provider's OAuth redirect (and, for Garmin and Strava, its webhooks): the A record to publish, the certificate's state, and whether the edge already serves it.\n\n- The domain is live when `state` is `ACTIVE` and `serving` is true. `FAILED`, or a reason such as `CAA`, names what to fix.\n- With none of its own, a domain another of your environments within the token's audience set up, which this one's stored redirect is on, is returned with `shared: true`. No domain is a 404.\n- Each call looks the hostname up in DNS and makes a TLS request to it, so poll every 5 seconds or slower.\n- 503 `service_unavailable`: custom domains are not available on this deployment; 503 `dependency_failed`: the certificate service did not answer.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. whoop. Case does not matter. An unrecognised provider is a 400, and one that does not use a custom domain (anything but whoop, dexcom, dexcom_eu, strava and garmin) is a 422. The provider does not need to be enabled."}]}}}}
```

## Set a provider's custom domain

> Claims a subdomain you own for the provider, starts its certificate, and returns the A record to publish at your DNS provider; Terra cannot publish it for you.\
> \
> \- Poll \`GET\` on this path until live, then point \`redirect\_url\` at it through the credentials \`PUT\` or \`PATCH\`.\
> \- Sending the hostname already set is not an error and changes nothing; one another of your environments within the token's audience set up for this provider is reused, with \`shared: true\`.\
> \- A different hostname replaces the current one only once nothing uses the old one: another of your environments redirecting to it, or Garmin webhooks pointing at it, is a 409 and nothing changes. The check covers every environment of the account, naming one only within the token's audience.\
> \- A hostname you use for a different provider, or one another account uses, is a 409.\
> \- A new certificate returns 201, anything else 200, with the domain as \`GET\` returns it minus the DNS and TLS probes.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"SourceDomain":{"type":"object","description":"A subdomain you own that a provider's OAuth redirect, and for some providers its webhooks, run through.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. whoop."},"hostname":{"type":"string","description":"The subdomain, lower-cased."},"state":{"type":"string","enum":["PROVISIONING","ACTIVE","FAILED"],"description":"PROVISIONING until the certificate is issued, then ACTIVE. FAILED needs the DNS record or CAA fixed; reason and detail say which."},"reason":{"type":["string","null"],"description":"Why issuance is failing, as a machine-readable reason such as CAA. Null while nothing is wrong."},"detail":{"type":["string","null"],"description":"What to fix, in words. Null while nothing is wrong."},"dns_record":{"description":"The DNS record to publish at your DNS provider.","$ref":"#/components/schemas/SourceDomainDnsRecord"},"resolved_ip":{"type":["string","null"],"description":"The address the hostname resolves to now, preferring one of Terra's edge addresses. Null when it does not resolve."},"resolved_ips":{"type":"array","description":"Every address the hostname publishes, both families. Empty when it does not resolve.","items":{"type":"string"}},"serving":{"type":"boolean","description":"Whether Terra's edge answers TLS for the hostname. Only true once ACTIVE, and only then is the domain live."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the certificate expires, as an ISO 8601 timestamp. Null until it is first issued."},"shared":{"type":"boolean","description":"Whether another of your environments holds the certificate and this one reuses it."},"redirect_served":{"type":"boolean","description":"Whether this environment's stored redirect for the provider is on this hostname."}},"required":["provider","hostname","state","reason","detail","dns_record","resolved_ip","resolved_ips","serving","expires_at","shared","redirect_served"]},"SourceDomainDnsRecord":{"type":"object","description":"The single record that points a subdomain at Terra's edge.","properties":{"type":{"type":"string","enum":["A"]},"name":{"type":"string","description":"The record name, which is the hostname."},"value":{"type":"string","description":"The address to point it at."}},"required":["type","name","value"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]},"SetSourceDomainRequest":{"type":"object","properties":{"hostname":{"type":"string","description":"A subdomain you own, e.g. whoop.acme.com. Use a different one for each provider."}},"required":["hostname"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/domain":{"put":{"operationId":"setSourceDomain","tags":["sources"],"responses":{"200":{"description":"Already set, replacing the current hostname, or reusing another of your environments' domain (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/SourceDomain"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"201":{"description":"A certificate is being provisioned for the hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDomain"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Set a provider's custom domain","description":"Claims a subdomain you own for the provider, starts its certificate, and returns the A record to publish at your DNS provider; Terra cannot publish it for you.\n\n- Poll `GET` on this path until live, then point `redirect_url` at it through the credentials `PUT` or `PATCH`.\n- Sending the hostname already set is not an error and changes nothing; one another of your environments within the token's audience set up for this provider is reused, with `shared: true`.\n- A different hostname replaces the current one only once nothing uses the old one: another of your environments redirecting to it, or Garmin webhooks pointing at it, is a 409 and nothing changes. The check covers every environment of the account, naming one only within the token's audience.\n- A hostname you use for a different provider, or one another account uses, is a 409.\n- A new certificate returns 201, anything else 200, with the domain as `GET` returns it minus the DNS and TLS probes.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. whoop. Case does not matter. An unrecognised provider is a 400, and one that does not use a custom domain (anything but whoop, dexcom, dexcom_eu, strava and garmin) is a 422. The provider does not need to be enabled."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSourceDomainRequest"}}}}}}}}
```

## Release a provider's custom domain

> Releases the certificate for this environment's custom domain for the provider, after which OAuth redirects and webhooks on the hostname stop working.\
> \
> \- It is a 409 while another of your environments still redirects to the hostname, naming it only when the token's audience includes it, or, for Garmin, while Garmin webhooks still point at it; a 503 means Garmin could not be read to check.\
> \- A domain another of your environments set up is never released from here, so an environment with none of its own gets a 204 and nothing changes.\
> \- The preview runs the same checks.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"UnprocessableEntity":{"description":"The request is well-formed but the target resource can't perform it (e.g. provider disallows custom credentials).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/domain":{"delete":{"operationId":"deleteSourceDomain","tags":["sources"],"responses":{"200":{"description":"Dry-run preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"204":{"description":"Released, or this environment had no domain of its own."},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Release a provider's custom domain","description":"Releases the certificate for this environment's custom domain for the provider, after which OAuth redirects and webhooks on the hostname stop working.\n\n- It is a 409 while another of your environments still redirects to the hostname, naming it only when the token's audience includes it, or, for Garmin, while Garmin webhooks still point at it; a 503 means Garmin could not be read to check.\n- A domain another of your environments set up is never released from here, so an environment with none of its own gets a 204 and nothing changes.\n- The preview runs the same checks.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. whoop. Case does not matter. An unrecognised provider is a 400, and one that does not use a custom domain (anything but whoop, dexcom, dexcom_eu, strava and garmin) is a 422."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}]}}}}
```

## Provider OAuth scopes

> Lists every scope the provider can request, sorted by scope.\
> \
> \- A required scope is always requested.\
> \- \`enabled\` says whether a new connection's OAuth request asks for the scope today: the environment's own choice when \`customised\` is true, and otherwise the scopes its selected data types need.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"ProviderScopes":{"type":"object","description":"Every OAuth scope a provider can request, and which of them this environment requests.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. fitbit."},"customised":{"type":"boolean","description":"Whether this environment has chosen its own scopes. false means it requests the scopes its selected data types need."},"scopes":{"type":"array","description":"Every scope the provider can request, sorted by scope. Empty, never null, for a provider with none.","items":{"$ref":"#/components/schemas/ProviderScope"}}},"required":["provider","customised","scopes"]},"ProviderScope":{"type":"object","description":"One OAuth scope a provider can request.","properties":{"scope":{"type":"string","description":"The scope as the provider names it."},"name":{"type":"string","description":"A display name, or an empty string when there is none."},"description":{"type":"string","description":"What the scope grants, or an empty string when there is no description."},"required":{"type":"boolean","description":"Whether the scope is always requested. A required scope cannot be switched off."},"enabled":{"type":"boolean","description":"Whether a new connection's OAuth request asks for this scope."}},"required":["scope","name","description","required","enabled"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/scopes":{"get":{"operationId":"getSourceScopes","tags":["sources"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderScopes"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Provider OAuth scopes","description":"Lists every scope the provider can request, sorted by scope.\n\n- A required scope is always requested.\n- `enabled` says whether a new connection's OAuth request asks for the scope today: the environment's own choice when `customised` is true, and otherwise the scopes its selected data types need.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400. The provider must be enabled; otherwise this is a 404."}]}}}}
```

## Set custom OAuth scopes

> Sets the scopes this environment requests from the provider to its required scopes plus the optional ones in the body, replacing any earlier choice.\
> \
> \- Every scope the provider does not accept is named in the 400, and then nothing is stored.\
> \- To go back to the scopes the selected data types need, use \`DELETE\` on this path.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"ProviderScopes":{"type":"object","description":"Every OAuth scope a provider can request, and which of them this environment requests.","properties":{"provider":{"type":"string","description":"The provider's slug, e.g. fitbit."},"customised":{"type":"boolean","description":"Whether this environment has chosen its own scopes. false means it requests the scopes its selected data types need."},"scopes":{"type":"array","description":"Every scope the provider can request, sorted by scope. Empty, never null, for a provider with none.","items":{"$ref":"#/components/schemas/ProviderScope"}}},"required":["provider","customised","scopes"]},"ProviderScope":{"type":"object","description":"One OAuth scope a provider can request.","properties":{"scope":{"type":"string","description":"The scope as the provider names it."},"name":{"type":"string","description":"A display name, or an empty string when there is none."},"description":{"type":"string","description":"What the scope grants, or an empty string when there is no description."},"required":{"type":"boolean","description":"Whether the scope is always requested. A required scope cannot be switched off."},"enabled":{"type":"boolean","description":"Whether a new connection's OAuth request asks for this scope."}},"required":["scope","name","description","required","enabled"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]},"ScopesRequest":{"type":"object","properties":{"scopes":{"type":"array","description":"The optional scopes to request. The provider's required scopes are always requested, whether listed or not, so an empty array requests only those. A scope the provider does not accept is a 400.","items":{"type":"string"}}},"required":["scopes"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/scopes":{"put":{"operationId":"setSourceScopes","tags":["sources"],"responses":{"200":{"description":"Updated (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/ProviderScopes"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Set custom OAuth scopes","description":"Sets the scopes this environment requests from the provider to its required scopes plus the optional ones in the body, replacing any earlier choice.\n\n- Every scope the provider does not accept is named in the 400, and then nothing is stored.\n- To go back to the scopes the selected data types need, use `DELETE` on this path.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400. The provider must be enabled."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopesRequest"}}}}}}}}
```

## Reset custom OAuth scopes

> Removes this environment's own scope choice for the provider, so new connections request the scopes its selected data types need.\
> \
> \- Existing connections keep the scopes they consented to.\
> \- Resetting a provider with no custom scopes succeeds and changes nothing; its preview says \`noop\`.\
> \- A \`?dry\_run=true\` preview shows the scopes \`GET\` on this path will then report.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"sources","summary":"Sources","description":"The wearables and apps your Unified API users can connect, with their credentials and sign-in settings."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["providers:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"schemas":{"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}}},"paths":{"/environments/{dev_id}/unified-api/sources/{provider}/scopes":{"delete":{"operationId":"resetSourceScopes","tags":["sources"],"responses":{"200":{"description":"Dry-run preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"204":{"description":"Reset, or there was nothing to reset."},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Reset custom OAuth scopes","description":"Removes this environment's own scope choice for the provider, so new connections request the scopes its selected data types need.\n\n- Existing connections keep the scopes they consented to.\n- Resetting a provider with no custom scopes succeeds and changes nothing; its preview says `noop`.\n- A `?dry_run=true` preview shows the scopes `GET` on this path will then report.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The provider this applies to, as a slug, e.g. garmin or apple_health. Case does not matter. An unrecognised provider is a 400. The provider must be enabled."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}]}}}}
```
