> ## Documentation Index > Fetch the complete documentation index at: https://developers.soxai.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # Require or release two-factor for a list of users > [Admin / PartnerAdmin / OrgAdmin] Bulk enable or disable 2FA requirement for a list of users. When required=True: Sets required=True on {uid}/totp_info (creates the document if absent). If the user has never enrolled TOTP, they will be forced to set it up on next login. If the user already has a confirmed TOTP setup, they will continue to use it. When required=False: Sets required=False and confirmed=False on {uid}/totp_info. Both fields must be cleared because the login flow checks confirmed first; leaving confirmed=True would still present the TOTP screen even if required=False. The stored secret is left in place but never reused: the next setup screen rotates it before displaying a QR code. A uid that belongs to no Firebase Auth user is reported in failed_uids with error USER_NOT_FOUND and is never written. Returns success_uids and failed_uids with per-uid error details. **Parameters** - Body (`TotpSetRequiredRequest`): `uid_list` (at most 200) and `required`. **Response** - `200` `{"success_uids", "failed_uids"}`. A uid that was refused by scope or that belongs to no account is in `failed_uids` with its reason; the rest are applied. **Errors** | Status | Condition | | --- | --- | | 400 | `uid_list` holds more than 200 entries | | 403 | The caller holds none of the three roles below | | 404 | The caller is an `OrgAdmin` whose own organization no longer exists. No uid is written | **Authorization** - Scheme: `Authorization: Bearer ` or `soxai-api-key: `. - `Admin`, `PartnerAdmin` or `OrgAdmin`. - The caller's scope **partitions** `uid_list` rather than admitting or refusing the whole request: uids the caller cannot reach are reported in `failed_uids` and left unwritten, while the rest are applied. A request naming only unreachable uids is therefore still a `200`. - `Admin` reaches every uid, `PartnerAdmin` the users registered under its own company, `OrgAdmin` the members of its own organization, and a caller holding both scoped roles the intersection. ## OpenAPI ````yaml /openapi-public.json post /oauth2/users/totp_required openapi: 3.1.0 info: title: SOXAI API description: > ## SOXAI API helps you get data stored in SOXAI database. Every endpoint below documents its own parameters, responses and authorization rule. ## How to use 1. All data-related endpoints need you to sign in first. Use the account you registered in the SOXAI app. 2. You can get a Bearer token and localID like this: ``` { "kind": "identitytoolkit#VerifyPasswordResponse", "registered": true, "localId": "[YOUR UID]", "email": "[YOUR EMAIL]", "idToken": "[YOUR BEARER TOKEN]", "refreshToken": [YOUR Refresh TOKEN]" } ``` use this `idToken` to fill it into the value field after you click **Authorize** button, or attach it to header in your request. For more info, search for "Bearer token". (ps. the difference between idToken and refreshToken: idToken will expire in 1 hour, refreshToken will expire in one month, you can use refreshToken to get new idToken when idToken expired.) 3. All users can access to his/her personal data with `localId` as user's uid. 4. If you are an organization admin, contact SOXAI first to create an organization. 5. After the organization is created, you can invite other users to join it. They receive an email to accept the invitation. 6. As an organization user, you can read your own data, plus the roster and profiles of your organization. Other members' measurement data is not yours to read - that is what an organization admin does. See "Who can read whose data" below. ## Quick start note for personal user 1. (Only once) Access `/api/login` to get your uid and OAuthToken by api, please memo OAuthToken, you can use it to access api without login again. 2. Access `/api/v2/DailyInfoData/{query_uid}` for day-level scores, or `/api/v2/DailyDetailData/{query_uid}` for the finer series. Both take a date range and return JSON, or a csv download when `format` is `csv`. 3. The v1 forms `/api/RawData/{query_uid}`, `/api/DailyInfoData/{query_uid}` and `/api/DailyDetailData/{query_uid}` return the same measurements under the raw database field names. Prefer the `/api/v2/` endpoints for a new integration. ## Quick start note for organization user 1. You will receive an email to accept the invitation from your organization admin. After you accept it, your data is shared with that admin. 2. If you want to query your own data, you can refer to the note for personal user. 3. You can query other orguser's info(email, uid, etc) after obtain your org_id from `/api/myOrg` and access `/api/orgs/{org_id}/orgUsers` ## Quick start note for organization admin 1. Contact SOXAI (info@soxai.co.jp) to create an organization for you. 2. Access `/api/login` to get your uid and OAuthToken by api. 3. Access `/api/myOrg` to get your organization id. 4. Access `/api/orgs/{org_id}/orgUsers` to create, read, update and delete organization users. When you post a new user, they receive an email to accept the invitation. 5. Access `/api/v2/DailyInfoDataForOrg` or `/api/v2/DailyDetailDataForOrg` to read your organization's members in one request. **You reach the SOXAI app data of the users who have agreed to share it**, and the endpoint narrows the answer to that set for you. ## Authentication and errors common to every endpoint Unless an endpoint says otherwise, it requires `Authorization: Bearer ` and answers: | Status | Condition | | --- | --- | | 401 | The `Authorization` header is missing, or the token is invalid or expired | | 403 | The caller is authenticated but not allowed to make this request. Each endpoint's **Authorization** block lists the bodies it uses | | 422 | The request did not match the schema. An **authorized** caller sees this instead of a 403; an unauthorized caller is refused before its body is read | | 429 | The rate limit was exceeded. Wait for `Retry-After` seconds before retrying | | 500 | Unexpected server-side failure | Each endpoint documents only the statuses that are specific to it. The **Authorization** block is the last section of every endpoint's description. For the endpoints that declare their rule on the route it is generated from that declaration, so it cannot disagree with what is enforced. ### The second credential `soxai-api-key: ` is accepted wherever `Authorization: Bearer ` is. The difference is lifetime and who issues it: an ID token expires in an hour and you mint it yourself from `POST /api/login`, while an API key is long-lived and read back from `GET /api-key/secret`. A request carries one or the other, not both. Server-to-server integrations should hold the key; anything acting on behalf of a signed-in person should hold the token, so that revoking the person's access is enough to stop it. ### Who can read whose data Which role you hold decides how far past your own uid you can read. A role is a claim on your credential, not something you pass as a parameter. | Role | Reaches | | --- | --- | | (none) | Only your own uid. Every user has this much | | `OrgUser` | Your own uid, plus your organization's roster and member profiles (email, uid, profile) - not other members' measurement data | | `OrgAdmin` | Every member of your own organization, including their measurement data | | `PartnerAdmin` | Every organization owned by your own company, and every member of those organizations | | `Admin` | Every user, with no company or organization scoping. Held by SOXAI only | One consequence catches integrators out: the roster an admin reaches is the whole roster, not only its active part. A membership's `status` records where a member stands in the invitation lifecycle; it does not by itself narrow what an admin can read. Do not infer a member's data scope from their `status` - read the endpoint's **Authorization** block, which states the rule that is actually enforced. ### v1 and v2 The data endpoints come in two generations. `/api/v2/...` returns standardized field names and is the interface to build against. The v1 endpoints (`/api/RawData`, `/api/DailyInfoData`, `/api/DailyDetailData`) return the raw database field names, which change when the database does. They are not deprecated and they are not going away without notice, but they will not gain fields that v2 has; a new integration should use v2. contact: name: SOXAI url: https://www.soxai.co.jp/contact email: info@soxai.co.jp version: 1.0.0 servers: - url: https://web-api.soxai.site description: Production security: [] tags: - name: Authentication description: >- Obtain and hold the credential every other endpoint asks for. `POST /api/login` returns the `idToken` you send as `Authorization: Bearer ` and the `refreshToken` that renews it; the password reset pair is here because a caller who has lost their password cannot hold a token either. `/app/me` reports what the credential you are holding actually carries, which is the first thing to check when an endpoint answers 403. The long-lived alternative to an ID token is under `API Keys`. - name: API Keys description: >- Issue and read back the caller's own long-lived API key, which is accepted as `soxai-api-key: ` wherever an ID token is. A caller holds one key at a time and reads it back rather than being shown it once. Hold a key for a server-to-server integration, where there is no signed-in person whose session could expire; hold an ID token from `Authentication` for anything acting on a person's behalf, so that revoking the person's access is enough to stop it. - name: Data (v2) description: >- Read measurement data with standardized field names. One endpoint per data shape for a single user (`DailyInfoData`, `DailyDetailData`, `DailyTrendData`) and the bulk forms for a whole organization or company (`...ForOrg`). This is the interface to build against. - name: Data (v1) description: >- Read measurement data with the raw database field names, one user at a time, as CSV or JSON. These endpoints are not deprecated and will not disappear without notice, but the names they return are the ones the database uses and change when it does, and they will not gain the fields `Data (v2)` has. **A new integration should use `Data (v2)`.** - name: Sync Status description: >- Whether a user's ring data arrived, rather than what it says. `ProcessLog/{query_uid}` returns one user's sync history and `LastProcessLog` the most recent entry. Read these before concluding that a missing day is missing rather than not yet uploaded - the data endpoints answer with what was received and cannot tell the two apart. - name: Organizations description: >- Create and manage organizations. An organization owns a member roster and is the unit every org-scoped endpoint addresses. A `PartnerAdmin` sees only the organizations its own company owns. - name: Organization Members description: >- Manage an organization's member roster: enrol members, invite them, edit their teams and admin flag, and remove them. A member reaches these endpoints only for the organization their own token names. `AcceptEmailVerification` is the other end of that flow - the link in the invitation email, which the invited user opens without being signed in. - name: Family Groups description: >- Small self-service groups where members choose, per metric, what they share with each other. Authority here comes from the caller's membership record and its `admin` / `member` role **inside the group** - a SOXAI `Admin`, `PartnerAdmin` or `OrgAdmin` claim grants nothing. `GroupView` is the single endpoint that returns members' health data. - name: Partner Companies description: >- Partner companies register and sign in **their own** users with certificates rather than through the SOXAI app. These are the endpoints the partner's own backend calls, authenticating with a signed certificate instead of a SOXAI token. The certificate itself is issued and revoked by SOXAI rather than through this API; contact SOXAI to obtain one. - name: Deep Links description: >- Deep links that carry a one-time token into the SOXAI app: group invitations, and sign-up links that prefill an email address. The token is the credential, so the endpoints that exchange one need no signed-in caller. - name: OAuth2 description: >- Sign a SOXAI user in to your own application with the OAuth2 authorization code flow. Your code reaches four of these: the discovery document your OIDC library reads, the URL you send the user's browser to, the token endpoint your backend calls with the authorization code, and the record of what the user consented to. The screens in between - the login form, the consent page and the two-factor prompts - are SOXAI's own pages, posted to by the browser, and your application never calls them. The remaining endpoint sets whether two-factor is required for a list of users, which an `OrgAdmin` or `PartnerAdmin` does for its own members. - name: Users description: >- Endpoints keyed on a user rather than on an organization: ring serial number lookup, and the caller's own ring sync history. - name: System description: >- Liveness and health checks for monitoring. `ping` answers from the process alone; `health` probes Firestore and both InfluxDB clients and answers `500` when one of them is unreachable; `health_check` reports the same dependencies one by one inside a `200`. None of these require authentication, and none of them read or write a user's data. paths: /oauth2/users/totp_required: post: tags: - OAuth2 summary: Require or release two-factor for a list of users description: >- [Admin / PartnerAdmin / OrgAdmin] Bulk enable or disable 2FA requirement for a list of users. When required=True: Sets required=True on {uid}/totp_info (creates the document if absent). If the user has never enrolled TOTP, they will be forced to set it up on next login. If the user already has a confirmed TOTP setup, they will continue to use it. When required=False: Sets required=False and confirmed=False on {uid}/totp_info. Both fields must be cleared because the login flow checks confirmed first; leaving confirmed=True would still present the TOTP screen even if required=False. The stored secret is left in place but never reused: the next setup screen rotates it before displaying a QR code. A uid that belongs to no Firebase Auth user is reported in failed_uids with error USER_NOT_FOUND and is never written. Returns success_uids and failed_uids with per-uid error details. **Parameters** - Body (`TotpSetRequiredRequest`): `uid_list` (at most 200) and `required`. **Response** - `200` `{"success_uids", "failed_uids"}`. A uid that was refused by scope or that belongs to no account is in `failed_uids` with its reason; the rest are applied. **Errors** | Status | Condition | | --- | --- | | 400 | `uid_list` holds more than 200 entries | | 403 | The caller holds none of the three roles below | | 404 | The caller is an `OrgAdmin` whose own organization no longer exists. No uid is written | **Authorization** - Scheme: `Authorization: Bearer ` or `soxai-api-key: `. - `Admin`, `PartnerAdmin` or `OrgAdmin`. - The caller's scope **partitions** `uid_list` rather than admitting or refusing the whole request: uids the caller cannot reach are reported in `failed_uids` and left unwritten, while the rest are applied. A request naming only unreachable uids is therefore still a `200`. - `Admin` reaches every uid, `PartnerAdmin` the users registered under its own company, `OrgAdmin` the members of its own organization, and a caller holding both scoped roles the intersection. operationId: admin_set_totp_required requestBody: content: application/json: schema: $ref: '#/components/schemas/TotpSetRequiredRequest' required: true responses: '200': description: >- Per-uid outcome. A uid refused by scope or belonging to no account comes back under failed_uids with its reason while the rest are applied. headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: {} example: success_count: 1 success_uids: - user123 failed_count: 1 failed_uids: - user789 out_of_scope_count: 0 out_of_scope_uids: [] '400': description: Bad Request - uid_list holds more entries than the per-request limit headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: bad-request error_msg: Too many uids. Maximum allowed is 200. '401': description: Unauthorized - the credentials are missing, expired or invalid headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: http-error error_msg: Invalid authentication credentials. '403': description: Forbidden - Not enough permission headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: forbidden error_msg: Not enough permission '404': description: >- Not Found - the caller is an OrgAdmin whose own organization no longer exists. No uid is written headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: not-found error_msg: Org '' not found '422': description: >- Unprocessable Entity - a request field does not meet the endpoint's validation rules content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unprocessable-entity error_msg: 'body.: ' '429': description: Too Many Requests - the rate limit was exceeded headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 Retry-After: description: >- Whole seconds to wait until both applicable buckets can accept one request. Returned only with a 429 response. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate-limited error_msg: Rate limit exceeded. Retry after seconds. '500': description: Internal Server Error - Failed to fetch data headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: internal-server-error error_msg: 'Failed to fetch data: ' security: - HTTPBearer: [] - SoxaiApiKey: [] components: schemas: TotpSetRequiredRequest: properties: uid_list: items: type: string type: array title: List of user IDs (max 200) description: User IDs to update. Supply at most 200 IDs. examples: - - user_123 required: type: boolean title: True to enforce 2FA, False to disable description: Whether two-factor authentication is required. examples: - true type: object required: - uid_list - required title: TotpSetRequiredRequest ErrorResponse: properties: error: type: string title: Error description: Machine-readable error category. examples: - bad-request error_msg: type: string title: Error Msg description: Human-readable explanation of the error; clients must not parse it. examples: - 'Invalid input: start_time must use YYYY-MM-DD.' type: object required: - error - error_msg title: ErrorResponse description: >- The body of every error answer: a machine-readable type and a human-readable message. securitySchemes: HTTPBearer: type: http scheme: bearer SoxaiApiKey: type: apiKey description: >- API key issued by `POST /api-key/secret`, sent in the `soxai-api-key` header. It is an alternative to the Bearer token, not an addition to it: when both are sent the Bearer token is used. The key carries the same roles as the user it was issued to, and expires after the number of days it was issued for. in: header name: soxai-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.