> 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/teams-api/authentication.md).

# Authentication

Create a Terra Widget session, where an athlete picks a wearable or app and signs in to connect it.

## Generate an authentication link, using the Terra Authentication Widget

> Returns a Terra Widget session with a hosted URL where the athlete 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 Team-Based API","version":"2026.11.19"},"tags":[{"name":"Authentication","summary":"Authentication","description":"Create a Terra Widget session, where an athlete picks a wearable or app and signs in to connect it."}],"servers":[{"url":"https://api.tryterra.co/v2/teams","description":"Main teams API base URL"}],"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"},"language":{"type":"string","description":"Display language of the widget"},"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"},"auth_failure_redirect_url":{"type":"string","description":"URL the user is redirected to upon unsuccessful authentication"}}},"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"]}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"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 an authentication link, using the Terra Authentication Widget","description":"Returns a Terra Widget session with a hosted URL where the athlete 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":"GenerateWidgetSession","parameters":[{"name":"dev-id","in":"header","description":"your developer ID","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"your API key","required":true,"schema":{"type":"string"}}],"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 an error happened (value is success)"},"expires_in":{"type":"number","description":"a number in seconds depicting how long the url is valid for"}}}}}},"400":{"description":"Returned when one or more parameters is malformed - an appropriate error message will be returned","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"a detailed message describing the error","type":"string"},"status":{"type":"string","enum":["success","error"],"description":"indicates that an error happened (value is error)"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Returned when credentials (dev ID and API key) are invalid","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"a detailed message describing the error","type":"string"},"status":{"type":"string","enum":["success","error"],"description":"indicates that an error happened (value is error)"}}}}}},"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"}}}}}}
```
