Soracom Auth and Access Management API

openapi: 3.0.0
info:
  title: Soracom and Query Analysis Auth API
  description: Run SQL queries against Soracom Query, fetch query schemas, and search SIMs, Inventory devices, and Sigfox devices.
  version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
  url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
  url: https://g.api.soracom.io/v1
tags:
- description: '- [Generate API key and token](/en/tools/api/key-and-token/)

    - Password reset token generation and verification

    - [Switch user](/en/docs/switch-user/) API key and token generation

    '
  name: Auth
paths:
  /auth:
    post:
      description: 'Performs authentication to access to the Soracom API. Please include the following information in your request.


        - To perform authentication by a root account, specify `email` and `password`.

        - To perform authentication by an AuthKey, specify `authKeyId` and `authKey`.

        - To perform authentication by a SAM user, specify `operatorId`, `userName` and `password`.


        An API key and API token will be included in the response if successful. Use the API key and API token to perform subsequent requests.

        '
      operationId: auth
      requestBody:
        content:
          application/json:
            examples:
              To perform authentication by a SAM user:
                value:
                  operatorId: OPXXXXXXXXXX
                  password: p@$$w0rd
                  userName: SORACOMAPI
              To perform authentication by a root account:
                value:
                  email: soracomapi@example.com
                  password: p@$$w0rd
              To perform authentication by an AuthKeyId and AuthKey:
                value:
                  authKey: secret-abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...
                  authKeyId: keyId-abcde12345fghij67890klmno12345pq
            schema:
              $ref: '#/components/schemas/AuthRequest'
        description: Authentication request.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
          description: Authentication successful.
        '401':
          description: Authentication failed.
      summary: Performs authentication to access to the Soracom API.
      tags:
      - Auth
      x-soracom-cli:
      - auth
  /auth/logout:
    post:
      description: Revokes the API key and API token that was used to call this API. Once revoked, the API key and API token cannot be used to make further requests to the API, regardless of the key and token's original expiration time. This API can be called regardless of any permission settings.
      operationId: logout
      responses:
        '204':
          description: Successfully revoked the API key and the API token.
      security:
      - api_key: []
        api_token: []
      summary: Revokes an API key and API token in order to remove access to the Soracom API.
      tags:
      - Auth
      x-soracom-cli:
      - logout
  /auth/password_reset_token/issue:
    post:
      description: Generates a password reset token and sends it to the operator's primary email address. After receiving the password reset token, call /v1/auth/password_reset_token/verify API with the token to update the operator's password.
      operationId: issuePasswordResetToken
      requestBody:
        content:
          application/json:
            example:
              email: soracomapi@example.com
            schema:
              $ref: '#/components/schemas/IssuePasswordResetTokenRequest'
        description: email address
        required: true
      responses:
        '200':
          description: Password reset token successfully sent to the specified email address.
        '400':
          description: Invalid email address.
      summary: Issues a password reset token for the operator.
      tags:
      - Auth
      x-soracom-cli:
      - auth issue-password-reset-token
  /auth/password_reset_token/verify:
    post:
      description: Updates the operator's password if the password reset token is verified.
      operationId: verifyPasswordResetToken
      requestBody:
        content:
          application/json:
            example:
              password: p@$$w0rd
              token: abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...
            schema:
              $ref: '#/components/schemas/VerifyPasswordResetTokenRequest'
        description: token, password
        required: true
      responses:
        '200':
          description: Password successfully updated.
        '400':
          description: Invalid token.
        '404':
          description: Token expired.
      summary: Verifies the password reset token and updates password.
      tags:
      - Auth
      x-soracom-cli:
      - auth verify-password-reset-token
  /auth/switch_user:
    post:
      description: Using the API key and API token of the original user, call this API to issue an API key and API token of the target user that you are switching to. The original user should already be registered in the target user's trust policy. See [User:updateUserTrustPolicy](#!/User/updateUserTrustPolicy) for information on updating the trust policy.
      operationId: switchUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchUserRequest'
        description: Specify the user to switch to and the validity period of the API token to be issued.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
          description: Authentication successful.
        '400':
          description: Switch user not allowed.
      security:
      - api_key: []
        api_token: []
      summary: Generates an API key and an API token to call APIs as a different user.
      tags:
      - Auth
      x-soracom-cli:
      - auth switch-user
components:
  schemas:
    VerifyPasswordResetTokenRequest:
      properties:
        password:
          type: string
        token:
          type: string
      required:
      - password
      - token
      type: object
    AuthResponse:
      properties:
        apiKey:
          example: api-abcde123-45fg-hij6-7890-klmno12345pq
          type: string
        operatorId:
          example: OPXXXXXXXXXX
          type: string
        token:
          example: abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...
          type: string
        userName:
          example: SORACOMAPI
          type: string
      type: object
    SwitchUserRequest:
      properties:
        operatorId:
          description: Operator ID to be switched to.
          type: string
        tokenTimeoutSeconds:
          default: 3600
          description: 'API key and API token validity period (in seconds) for the switched user. The default is 3600 seconds (1 hour). The minimum and maximum values are also shown below.


            - Minimum: 180 seconds (3 minutes)

            - Maximum value: 3600 seconds (1 hour)

            '
          maximum: 3600
          minimum: 180
          type: integer
        userName:
          description: The SAM user name of the specified operator ID to be switched to.
          type: string
      type: object
    AuthRequest:
      properties:
        authKey:
          type: string
        authKeyId:
          type: string
        email:
          type: string
        mfaOTPCode:
          type: string
        operatorId:
          type: string
        password:
          type: string
        tokenTimeoutSeconds:
          default: 86400
          format: int64
          maximum: 172800
          type: integer
        userName:
          type: string
      type: object
    IssuePasswordResetTokenRequest:
      properties:
        email:
          type: string
      required:
      - email
      type: object
  securitySchemes:
    api_key:
      description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API.

        Required in combination with an API token for all authenticated requests.

        '
      in: header
      name: X-Soracom-API-Key
      type: apiKey
    api_token:
      description: 'API token for authentication. This token has an expiration time and must be refreshed periodically.

        Required in combination with an API key for all authenticated requests.'
      in: header
      name: X-Soracom-Token
      type: apiKey