App users ¶
app-users¶
POST /api/v1/applications/{application_id}/users¶
Create App User (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
Find or create a user that belongs to your app.
A new user answers 201, and you can mint a token for them right away
(POST .../users/{user_id}/token). An email, if given, is unverified until the
person confirms it through the message SweatStack sends; external_reference is your own id for
the user, unique within your app. If a user already has that external_reference the answer is
200 with that user, unchanged, so you need no read before the write. Requires that you accepted
the developer terms and the Data Processing Agreement for the app on its Consent screen tab.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
refreshed-token |
header | No | |||
token |
cookie | string | No |
Request body
{
"first_name": null,
"last_name": null,
"email": null,
"external_reference": null
}
Schema of the request body
{
"properties": {
"first_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100,
"minLength": 1
},
{
"type": "null"
}
],
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"title": "Last Name"
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"title": "Email"
},
"external_reference": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"title": "External Reference"
}
},
"type": "object",
"title": "AppManagedUserCreate",
"description": "A user an app creates for itself (plan 082, the management API). The email, if given, is\nunverified until the athlete confirms it; `external_reference` is the app's own id for the\nuser, unique within the app."
}
Responses
{
"id": "string",
"first_name": null,
"last_name": null,
"email": null,
"email_verified": true,
"external_reference": null,
"registered_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Name"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"email_verified": {
"type": "boolean",
"title": "Email Verified"
},
"external_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "External Reference"
},
"registered_at": {
"type": "string",
"format": "date-time",
"title": "Registered At"
}
},
"type": "object",
"required": [
"id",
"first_name",
"last_name",
"email",
"email_verified",
"external_reference",
"registered_at"
],
"title": "AppManagedUserResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /api/v1/applications/{application_id}/users¶
List App Users (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
The users that belong to your app, oldest first.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
email |
query | No | Only the user with this email address. | ||
external_reference |
query | No | Only the user with this reference of yours. | ||
refreshed-token |
header | No | |||
token |
cookie | string | No |
Responses
[
{
"id": "string",
"first_name": null,
"last_name": null,
"email": null,
"email_verified": true,
"external_reference": null,
"registered_at": "2022-04-13T15:42:05.901Z"
}
]
Schema of the response body
{
"type": "array",
"items": {
"$ref": "#/components/schemas/AppManagedUserResponse"
},
"title": "Response List App Users Api V1 Applications Application Id Users Get"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /api/v1/applications/{application_id}/users/{user_id}¶
Get App User (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
One user of your app.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Responses
{
"id": "string",
"first_name": null,
"last_name": null,
"email": null,
"email_verified": true,
"external_reference": null,
"registered_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Name"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"email_verified": {
"type": "boolean",
"title": "Email Verified"
},
"external_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "External Reference"
},
"registered_at": {
"type": "string",
"format": "date-time",
"title": "Registered At"
}
},
"type": "object",
"required": [
"id",
"first_name",
"last_name",
"email",
"email_verified",
"external_reference",
"registered_at"
],
"title": "AppManagedUserResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
PATCH /api/v1/applications/{application_id}/users/{user_id}¶
Update App User (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
Change a user's name. An email address is changed through SweatStack support.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Request body
{
"first_name": null,
"last_name": null
}
Schema of the request body
{
"properties": {
"first_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100,
"minLength": 1
},
{
"type": "null"
}
],
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"title": "Last Name"
}
},
"type": "object",
"title": "AppManagedUserUpdate",
"description": "The name only (plan 082 D19): an email change goes through support."
}
Responses
{
"id": "string",
"first_name": null,
"last_name": null,
"email": null,
"email_verified": true,
"external_reference": null,
"registered_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Name"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"email_verified": {
"type": "boolean",
"title": "Email Verified"
},
"external_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "External Reference"
},
"registered_at": {
"type": "string",
"format": "date-time",
"title": "Registered At"
}
},
"type": "object",
"required": [
"id",
"first_name",
"last_name",
"email",
"email_verified",
"external_reference",
"registered_at"
],
"title": "AppManagedUserResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
DELETE /api/v1/applications/{application_id}/users/{user_id}¶
Delete App User (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
Delete a user of your app and all their data. Irreversible.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Responses
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /api/v1/applications/{application_id}/users/{user_id}/token¶
Mint App User Token (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
An access token for one of your users. It holds your app's default scopes as they are
when you ask, so a change on the Consent screen tab reaches every user with their next token.
Send scope to get a token that holds only a part of them; a scope outside them answers
400. There is no refresh token: when it runs out, ask for another. Every token counts the
user as active.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Request body
Schema of the request body
{
"anyOf": [
{
"$ref": "#/components/schemas/AppUserTokenRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
Responses
{
"access_token": "string",
"token_type": "string",
"expires_in": 0,
"refresh_token": null,
"scope": null,
"id_token": null
}
Schema of the response body
{
"properties": {
"access_token": {
"type": "string",
"title": "Access Token"
},
"token_type": {
"type": "string",
"const": "Bearer",
"title": "Token Type",
"default": "Bearer"
},
"expires_in": {
"type": "integer",
"title": "Expires In"
},
"refresh_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Refresh Token"
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Scope"
},
"id_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id Token"
}
},
"type": "object",
"required": [
"access_token",
"expires_in"
],
"title": "TokenResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
PUT /api/v1/applications/{application_id}/users/{user_id}/connections/{provider}¶
Declare App User Connection (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
State that one of your users is connected to a platform your app runs itself, and what that connection provides, in the vocabulary of the account status response.
Send it on consent, on a permission change and when a backfill completes: SweatStack's account
status and the Portal read it like a connection of its own. A syncing older than a day reads
ready. Answers 409 unless the platform is set to self-hosted on your app's Data sources tab.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
provider |
path | No | |||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Request body
{
"capabilities": {},
"connected_at": null
}
Schema of the request body
{
"properties": {
"capabilities": {
"additionalProperties": {
"$ref": "#/components/schemas/CapabilityStatus"
},
"propertyNames": {
"$ref": "#/components/schemas/Capability"
},
"type": "object",
"title": "Capabilities"
},
"connected_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Connected At",
"description": "When the user connected, if not now. Kept across later declarations; never in the future."
}
},
"type": "object",
"required": [
"capabilities"
],
"title": "ConnectionDeclaration",
"description": "A connection your app states for one of its users (plan 097 D25), in the vocabulary of the\naccount status response. A capability you leave out reads `unavailable`."
}
Responses
{
"provider": "garmin_connect",
"capabilities": {},
"connected_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"provider": {
"$ref": "#/components/schemas/IntegrationName"
},
"capabilities": {
"additionalProperties": {
"$ref": "#/components/schemas/CapabilityStatus"
},
"propertyNames": {
"$ref": "#/components/schemas/Capability"
},
"type": "object",
"title": "Capabilities"
},
"connected_at": {
"type": "string",
"format": "date-time",
"title": "Connected At"
}
},
"type": "object",
"required": [
"provider",
"capabilities",
"connected_at"
],
"title": "ConnectionResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
DELETE /api/v1/applications/{application_id}/users/{user_id}/connections/{provider}¶
Delete App User Connection (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
State that one of your users is no longer connected to a platform your app runs itself, for instance on a deregistration. Safe to repeat. The user and their data stay.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
provider |
path | No | |||
refreshed-token |
header | No | |||
token |
cookie | string | No | ||
user_id |
path | string | No |
Responses
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
PUT /api/v1/applications/{application_id}/connections/{provider}/{subject}¶
Declare Connection By Subject (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
State what a connection provides, by your issuer's own sub for the person, and learn which
of your users it is.
For an integration that signs athletes in as an OpenID Provider. Send it after the platform's
consent with the state of the authorization request, and again on a permission change and when
a backfill completes. The answer's user_id is the user to upload for. It is null while
SweatStack does not know yet whose connection this is, which lasts until the person's browser is
back at SweatStack: wait, and ask again. A sign-in by someone new gets its user at once.
Answers 409 unless the platform is set to self-hosted with an issuer on your app's Data sources
tab.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
provider |
path | No | |||
refreshed-token |
header | No | |||
subject |
path | string | No | Your issuer's `sub` for the person. | |
token |
cookie | string | No |
Request body
{
"capabilities": {},
"connected_at": null,
"state": null,
"platform_user_id": null
}
Schema of the request body
{
"properties": {
"capabilities": {
"additionalProperties": {
"$ref": "#/components/schemas/CapabilityStatus"
},
"propertyNames": {
"$ref": "#/components/schemas/Capability"
},
"type": "object",
"title": "Capabilities"
},
"connected_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Connected At",
"description": "When the user connected, if not now. Kept across later declarations; never in the future."
},
"state": {
"anyOf": [
{
"type": "string",
"maxLength": 8000
},
{
"type": "null"
}
],
"title": "State",
"description": "The `state` of the authorization request this call is made during, unchanged. Leave it out on later calls: it is read only for a subject SweatStack does not know yet."
},
"platform_user_id": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Platform User Id",
"description": "The platform's own id for the person, sent with `state`. SweatStack reads it once, to recognise a SweatStack account that already uses your app through this platform, and does not store it. Such a person is asked whether to move that account to your app, and `user_id` stays `null` until they have answered."
}
},
"type": "object",
"required": [
"capabilities"
],
"title": "SubjectConnectionDeclaration",
"description": "A connection an OpenID Provider states by its own `sub` for the person (plan 097 D44)."
}
Responses
{
"provider": "garmin_connect",
"capabilities": {},
"connected_at": "2022-04-13T15:42:05.901Z",
"user_id": null
}
Schema of the response body
{
"properties": {
"provider": {
"$ref": "#/components/schemas/IntegrationName"
},
"capabilities": {
"additionalProperties": {
"$ref": "#/components/schemas/CapabilityStatus"
},
"propertyNames": {
"$ref": "#/components/schemas/Capability"
},
"type": "object",
"title": "Capabilities"
},
"connected_at": {
"type": "string",
"format": "date-time",
"title": "Connected At"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id",
"description": "The user this subject is. `null` until SweatStack has linked the subject: wait, and ask again."
}
},
"type": "object",
"required": [
"provider",
"capabilities",
"connected_at",
"user_id"
],
"title": "SubjectConnectionResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
DELETE /api/v1/applications/{application_id}/connections/{provider}/{subject}¶
Delete Connection By Subject (beta)
Description
Beta. This endpoint is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
State that the connection of this sub is over, for instance on a deregistration. Safe to
repeat. The user and their data stay, and the same sub later is the same user.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
application_id |
path | string | No | ||
provider |
path | No | |||
refreshed-token |
header | No | |||
subject |
path | string | No | Your issuer's `sub` for the person. | |
token |
cookie | string | No |
Responses
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Schemas¶
AppManagedUserCreate¶
| Name | Type | Description |
|---|---|---|
email |
||
external_reference |
||
first_name |
||
last_name |
AppManagedUserResponse¶
| Name | Type | Description |
|---|---|---|
email |
||
email_verified |
boolean | |
external_reference |
||
first_name |
||
id |
string | |
last_name |
||
registered_at |
string(date-time) |
AppManagedUserUpdate¶
| Name | Type | Description |
|---|---|---|
first_name |
||
last_name |
AppUserTokenRequest¶
| Name | Type | Description |
|---|---|---|
scope |
The scopes the token should hold, separated by spaces, each among your app's default scopes. Leave it out for all of them. `offline_access` is never among them: this token has no refresh token. |
Capability¶
Type: string
CapabilityStatus¶
Type: string
ConnectionDeclaration¶
| Name | Type | Description |
|---|---|---|
capabilities |
||
connected_at |
When the user connected, if not now. Kept across later declarations; never in the future. |
ConnectionResponse¶
| Name | Type | Description |
|---|---|---|
capabilities |
||
connected_at |
string(date-time) | |
provider |
IntegrationName |
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
IntegrationName¶
Type: string
SubjectConnectionDeclaration¶
| Name | Type | Description |
|---|---|---|
capabilities |
||
connected_at |
When the user connected, if not now. Kept across later declarations; never in the future. | |
platform_user_id |
The platform's own id for the person, sent with `state`. SweatStack reads it once, to recognise a SweatStack account that already uses your app through this platform, and does not store it. Such a person is asked whether to move that account to your app, and `user_id` stays `null` until they have answered. | |
state |
The `state` of the authorization request this call is made during, unchanged. Leave it out on later calls: it is read only for a subject SweatStack does not know yet. |
SubjectConnectionResponse¶
| Name | Type | Description |
|---|---|---|
capabilities |
||
connected_at |
string(date-time) | |
provider |
IntegrationName | |
user_id |
The user this subject is. `null` until SweatStack has linked the subject: wait, and ask again. |
TokenResponse¶
| Name | Type | Description |
|---|---|---|
access_token |
string | |
expires_in |
integer | |
id_token |
||
refresh_token |
||
scope |
||
token_type |
string |
ValidationError¶
| Name | Type | Description |
|---|---|---|
loc |
Array<> | |
msg |
string | |
type |
string |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| HTTPBearer | http | bearer | |
| HTTPBasic | http | basic |