> 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/health-and-fitness-api/authentication.md).

# Authentication

Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user.

## Generate an authentication link

> Returns a login URL for one provider; redirect the end user to it to connect their account.\
> \
> \- The outcome arrives as an \`auth\` event: type \`auth\` on success, \`auth\_cancelled\` if the login fails or is abandoned.\
> \- Refused with \`402\` once your environment is past its user limit.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"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"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","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","code"]}}},"paths":{"/auth/authenticateUser":{"post":{"summary":"Generate an authentication link","description":"Returns a login URL for one provider; redirect the end user to it to connect their account.\n\n- The outcome arrives as an `auth` event: type `auth` on success, `auth_cancelled` if the login fails or is abandoned.\n- Refused with `402` once your environment is past its user limit.","tags":["Authentication"],"operationId":"Authentication_AuthenticateUser","parameters":[{"name":"resource","in":"query","description":"Provider to connect, such as `FITBIT`, `GARMIN` or `OURA`; `GET /integrations/detailed` lists them. An unknown provider, or one not enabled in your environment, is refused with `400`.","schema":{"type":"string"},"required":true},{"name":"dev-id","in":"header","description":"your developer ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"reference_id":{"type":"string"},"auth_success_redirect_url":{"type":"string"},"auth_failure_redirect_url":{"type":"string"},"sdk_app":{"type":"string","enum":["avengers","grip"],"description":"Which Terra reference app an SDK authentication link hands the end user to. For APPLE_HEALTH, \"avengers\" or \"grip\" is required; omitting it is rejected with a 400 unless the legacy use_terra_avengers_app is true, which selects Terra Avengers. For HEALTH_CONNECT and SAMSUNG, \"grip\" is required; any other value or omitting it is rejected with a 400. The link carries a resource query parameter (APPLE, HEALTH_CONNECT or SAMSUNG) naming the connection the app opens. Sending this for any other resource has no effect."}}}}},"required":false},"responses":{"200":{"description":"Returned when authentication link could be successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success","error"],"description":"indicates that the request was successful"},"user_id":{"description":"User ID for the user being created","type":"string"},"auth_url":{"type":"string","description":"authentication URL the user must be redirected to in order to link their account"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Generate a Terra Widget session link

> Returns a Terra Widget session with a hosted URL where the end user selects a provider and logs in.\
> \
> \- Accounts created after 3 September 2026 get \`410 Gone\`; create widget sessions with \`POST <https://access.tryterra.co/api/widget/session\\`> instead.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"WidgetSessionParams":{"type":"object","properties":{"providers":{"type":"string","description":"Comma separated list of providers to display on the device selection page. The legacy wildcard ALL means every provider enabled on your dashboard, the same as omitting the field."},"reference_id":{"type":"string","description":"Identifier of the end user on your system, such as a user ID or email associated with them"},"auth_success_redirect_url":{"type":"string","description":"URL the user is redirected to upon successful authentication. The legacy value multi-auth is honoured and sets multi_auth instead of acting as a URL."},"auth_failure_redirect_url":{"type":"string","description":"URL the user is redirected to upon unsuccessful authentication"},"use_terra_avengers_app":{"type":"boolean","description":"Complete Apple Health connections in the Terra Avengers app instead of your own app. sdk_app takes precedence where both apply."},"sdk_app":{"type":"string","enum":["avengers","grip"],"description":"Terra mobile app that completes connections to providers with no web login, instead of your own app. grip (Terra Grip) covers APPLE, HEALTH_CONNECT and SAMSUNG; avengers (Terra Avengers) covers APPLE. Other on-device providers keep the default redirect to auth_success_redirect_url with resource and user_id=null. Takes precedence over use_terra_avengers_app where both apply; apple_app_url and samsung_app_url take precedence over both. Any other value is rejected with a 400."},"connected_uids":{"type":"array","description":"Terra user IDs already connected for this end user; their providers show as connected with a disconnect option","items":{"type":"string"}},"show_disconnect":{"type":"boolean","description":"Show disconnect buttons for providers already connected under reference_id"},"multi_auth":{"type":"boolean","description":"Keep the user on the widget after each successful connection so they can connect several providers in one session"},"bypass_feedback":{"type":"boolean","description":"When false, the user stays on the widget's own result screen instead of being redirected immediately"},"apple_app_url":{"type":"string","description":"URL of your own iOS app to hand Apple Health connections to, instead of the Terra mobile app"},"samsung_app_url":{"type":"string","description":"URL of your own Android app to hand Samsung Health connections to"},"language":{"type":"string","description":"forces the widget UI language (e.g. en, fr, ja, zh_cn); unsupported codes fall back to the end user's browser language"}}},"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"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","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","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/auth/generateWidgetSession":{"post":{"summary":"Generate a Terra Widget session link","description":"Returns a Terra Widget session with a hosted URL where the end user selects a provider and logs in.\n\n- Accounts created after 3 September 2026 get `410 Gone`; create widget sessions with `POST https://access.tryterra.co/api/widget/session` instead.","tags":["Authentication"],"operationId":"Authentication_GenerateWidgetSession","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetSessionParams"}}},"required":true},"responses":{"200":{"description":"Returned when authentication link could be successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"description":"Session ID for the widget authentication session","type":"string"},"url":{"type":"string","description":"the widget URL the user must be redirected to in order to link their account"},"status":{"type":"string","enum":["success","error"],"description":"indicates that the request was successful (value is success)"},"expires_in":{"type":"number","description":"a number in seconds depicting how long the url is valid for"},"warnings":{"type":"array","items":{"type":"string"},"description":"present when part of the request could not be honoured, such as requested providers that are unknown or not enabled"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"410":{"description":"Returned for Terra accounts created after the widget relaunch (2026-09-03) — this endpoint is deprecated for them. Create widget sessions with POST https://access.tryterra.co/api/widget/session instead. The response carries Deprecation and Link (rel=\"deprecation\") headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Deauthenticate a user

> Revokes Terra's access to the user's provider data.\
> \
> \- Cannot be undone: the end user has to connect again for data to resume.\
> \- Sends a \`deauth\` event for the user.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","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","code"]},"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"]}}},"paths":{"/auth/deauthenticateUser":{"delete":{"summary":"Deauthenticate a user","description":"Revokes Terra's access to the user's provider data.\n\n- Cannot be undone: the end user has to connect again for data to resume.\n- Sends a `deauth` event for the user.","tags":["Authentication"],"operationId":"Authentication_DeauthenticateUser","parameters":[{"name":"user_id","in":"query","description":"Terra user ID (a UUID) of the user to deauthenticate.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Returned when user is successfully deauthenticated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["success","error"],"description":"indicates that the deauthentication was successful (value is success)","type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Generate a mobile SDK auth token

> Creates a token that a Terra mobile SDK passes to \`initConnection()\` to create a user for Apple Health, Samsung Health or a similar on-device provider.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","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","code"]},"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"]}}},"paths":{"/auth/tokens":{"post":{"tags":["Authentication"],"summary":"Generate a mobile SDK auth token","description":"Creates a token that a Terra mobile SDK passes to `initConnection()` to create a user for Apple Health, Samsung Health or a similar on-device provider.","operationId":"Authentication_CreateAuthToken","parameters":[{"name":"reference_id","in":"query","description":"Your identifier for the end user this token is being issued for. When supplied, the token is bound to it and redemption ignores the reference_id the SDK sends, so a token cannot be used to attach a device to a different user. Omit to keep the SDK-supplied value.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"token":{"type":"string"},"expires_in":{"type":"integer","default":0}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Generate a mobile SDK auth token (deprecated)

> Same as \`POST /auth/tokens\`, under the older path that shipped mobile SDK versions call.\
> \
> \- Stays available indefinitely; new integrations should use \`POST /auth/tokens\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Connect a user's wearable or app through a link or the Terra Widget, issue mobile SDK tokens, and disconnect a user."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","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","code"]},"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"]}}},"paths":{"/auth/generateAuthToken":{"post":{"tags":["Authentication"],"summary":"Generate a mobile SDK auth token (deprecated)","description":"Same as `POST /auth/tokens`, under the older path that shipped mobile SDK versions call.\n\n- Stays available indefinitely; new integrations should use `POST /auth/tokens`.","operationId":"Authentication_GenerateAuthToken","parameters":[{"name":"reference_id","in":"query","description":"Your identifier for the end user this token is being issued for. When supplied, the token is bound to it and redemption ignores the reference_id the SDK sends, so a token cannot be used to attach a device to a different user. Omit to keep the SDK-supplied value.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"token":{"type":"string"},"expires_in":{"type":"integer","default":0}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}},"deprecated":true}}}}
```
