openapi: 3.0.0
info:
  title: Soracom and Query Analysis Role 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: '[Access management (Soracom Access Management)](/en/docs/sam/)'
  name: Role
paths:
  /operators/{operator_id}/roles:
    get:
      description: Returns a list of roles.
      operationId: listRoles
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: 'Filters by the type of the role. Specify one of the following:

          - `operator`: Operator managed role (default)

          - `soracom`: Soracom managed role

          - `all`: All roles

          '
        in: query
        name: owner
        required: false
        schema:
          enum:
          - operator
          - soracom
          - all
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ListRolesResponse'
                type: array
          description: OK.
      security:
      - api_key: []
        api_token: []
      summary: List Roles
      tags:
      - Role
      x-soracom-cli:
      - roles list
  /operators/{operator_id}/roles/{role_id}:
    delete:
      description: Deletes an operator managed role.
      operationId: deleteRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: Role ID.
        in: path
        name: role_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The role was deleted.
        '400':
          description: The role is still in use.
        '404':
          description: Role not found.
      security:
      - api_key: []
        api_token: []
      summary: Delete Operator Managed Role
      tags:
      - Role
      x-soracom-cli:
      - roles delete
    get:
      description: Retrieves a role.
      operationId: getRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: 'Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

          '
        in: path
        name: role_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
          description: OK.
        '404':
          description: Role not found.
      security:
      - api_key: []
        api_token: []
      summary: Get Role
      tags:
      - Role
      x-soracom-cli:
      - roles get
    post:
      description: Adds a new operator managed role.
      operationId: createRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: Role ID.
        in: path
        name: role_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateRoleRequest'
        description: Permission.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRoleResponse'
          description: OK.
        '400':
          description: Failed to create an operator managed role.
      security:
      - api_key: []
        api_token: []
      summary: Create Operator Managed Role
      tags:
      - Role
      x-soracom-cli:
      - roles create
    put:
      description: Edits an operator managed role.
      operationId: updateRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: Role ID.
        in: path
        name: role_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateRoleRequest'
        description: Permission.
        required: true
      responses:
        '200':
          description: OK.
        '404':
          description: Operator managed role not found.
      security:
      - api_key: []
        api_token: []
      summary: Update Operator Managed Role
      tags:
      - Role
      x-soracom-cli:
      - roles update
  /operators/{operator_id}/roles/{role_id}/users:
    get:
      description: Retrieves a list of users attached to a role.
      operationId: listRoleAttachedUsers
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: 'Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

          '
        in: path
        name: role_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserDetailResponse'
                type: array
          description: OK.
        '404':
          description: Role not found.
      security:
      - api_key: []
        api_token: []
      summary: List Role Attached Users
      tags:
      - Role
      x-soracom-cli:
      - roles list-users
  /operators/{operator_id}/roles/{role_id}/versions:
    get:
      description: Retrieves a list of versions for a Soracom managed role.
      operationId: listRoleVersions
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: SRN (Soracom Resource Name) of the Soracom managed role. The format is `srn:soracom:::Role:[roleName]`.
        in: path
        name: role_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RoleVersionResponse'
                type: array
          description: OK.
        '400':
          description: Operator managed roles cannot be specified.
        '404':
          description: Soracom managed role not found.
      security:
      - api_key: []
        api_token: []
      summary: Get Soracom Managed Role Versions
      tags:
      - Role
      x-soracom-cli:
      - roles list-versions
  /operators/{operator_id}/users/{user_name}/roles:
    get:
      description: Retrieves a list of the user's roles.
      operationId: listUserRoles
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: SAM user name.
        in: path
        name: user_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RoleResponse'
                type: array
          description: OK.
        '404':
          description: SAM user not found.
      security:
      - api_key: []
        api_token: []
      summary: List User Roles
      tags:
      - Role
      x-soracom-cli:
      - users list-roles
    post:
      description: Attaches a role to a user.
      operationId: attachRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: SAM user name.
        in: path
        name: user_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachRoleRequest'
        description: Role ID.
        required: true
      responses:
        '200':
          description: OK.
        '400':
          description: The role has already been attached or not found.
        '404':
          description: SAM user not found.
      security:
      - api_key: []
        api_token: []
      summary: Attach Role to User
      tags:
      - Role
      x-soracom-cli:
      - users attach-role
  /operators/{operator_id}/users/{user_name}/roles/{role_id}:
    delete:
      description: Detaches a role from a user.
      operationId: detachRole
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: SAM user name.
        in: path
        name: user_name
        required: true
        schema:
          type: string
      - description: 'Role ID. For operator managed roles, specify the role ID provided during role creation. For Soracom managed roles, specify in SRN (Soracom Resource Name) format.

          '
        in: path
        name: role_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK.
        '404':
          description: SAM user or role not found.
      security:
      - api_key: []
        api_token: []
      summary: Detach Role from User
      tags:
      - Role
      x-soracom-cli:
      - users detach-role
components:
  schemas:
    RoleVersionResponse:
      properties:
        description:
          description: The description of the Soracom managed role.
          type: string
        owner:
          description: 'The type of the role.

            - `soracom`: Soracom managed role

            '
          enum:
          - operator
          - soracom
          type: string
        permission:
          description: Permission as JSON for the Soracom managed role.
          type: string
        publishDateTime:
          description: The publish date and time of the Soracom managed role version (UNIX time in seconds).
          format: int64
          type: integer
        roleId:
          description: SRN (Soracom Resource Name) format ID of the Soracom managed role.
          type: string
        roleName:
          description: Resource name part of the SRN (Soracom Resource Name) of the Soracom managed role (e.g., `srn:soracom:::Role:[roleName]`).
          example: my-role
          type: string
        version:
          description: The version number of the Soracom managed role.
          format: int64
          type: integer
      type: object
    CreateRoleResponse:
      properties:
        roleId:
          description: The role ID.
          type: string
      type: object
    CreateOrUpdateRoleRequest:
      properties:
        description:
          description: The description of the operator managed role.
          type: string
        permission:
          description: Permission as JSON for the operator managed role.
          type: string
      required:
      - permission
      type: object
    AuthKeyResponse:
      properties:
        authKeyId:
          description: The ID of the authentication key.
          example: keyId-xxx
          type: string
        createDateTime:
          description: The creation date and time of the authentication key (UNIX time in seconds).
          example: 1722480500
          format: int64
          type: integer
        lastUsedDateTime:
          description: The last used date and time of the authentication key (UNIX time in seconds).
          example: 1722480600
          format: int64
          type: integer
      required:
      - authKeyId
      - createDateTime
      type: object
    RoleResponse:
      properties:
        createDateTime:
          description: The creation date and time of the role (UNIX time in seconds).
          format: int64
          type: integer
        description:
          description: The description of the role.
          type: string
        owner:
          description: 'The type of the role. It can be one of the following:

            - `operator`: Operator managed role

            - `soracom`: Soracom managed role

            '
          enum:
          - operator
          - soracom
          type: string
        permission:
          description: Permission as JSON.
          type: string
        roleId:
          description: Role ID. For operator managed roles, this is the role ID specified at creation. For Soracom managed roles, this will be in SRN (Soracom Resource Name) format.
          type: string
        roleName:
          description: Role name. For operator managed roles, this will be the same as `roleId`. For Soracom managed roles, this will be the resource name part of the SRN (e.g., `srn:soracom:::Role:[roleName]`).
          example: my-role
          type: string
        updateDateTime:
          description: The update date and time of the role (UNIX time in seconds).
          format: int64
          type: integer
      type: object
    UserDetailResponse:
      properties:
        authKeyList:
          description: A list of authentication keys.
          items:
            $ref: '#/components/schemas/AuthKeyResponse'
          type: array
        createDateTime:
          description: The creation date and time of the SAM user (UNIX time in seconds).
          example: 1722480500
          format: int64
          type: integer
        description:
          description: The description of the SAM user.
          example: This is my user
          type: string
        hasPassword:
          description: Whether the login password for the Soracom User Console has been set.
          type: boolean
        permission:
          description: The permission of the SAM user.
          example: '{"statements":[{"api":"*","effect":"allow"}]}'
          type: string
        roleList:
          description: A list of roles assigned to the SAM user.
          items:
            $ref: '#/components/schemas/ListRolesResponse'
          type: array
        updateDateTime:
          description: The update date and time of the SAM user (UNIX time in seconds).
          example: 1722480600
          format: int64
          type: integer
        userName:
          description: The name of the SAM user.
          example: my-user
          type: string
      required:
      - authKeyList
      - createDateTime
      - hasPassword
      - roleList
      - updateDateTime
      - userName
      type: object
    ListRolesResponse:
      properties:
        createDateTime:
          description: The creation date and time of the role (UNIX time in seconds).
          example: 1722480500
          format: int64
          type: integer
        description:
          description: The description of the role.
          example: This is my role
          type: string
        owner:
          description: 'The type of the role. It can be one of the following:

            - soracom: Soracom managed role

            - operator: Operator managed role

            '
          enum:
          - operator
          - soracom
          type: string
        roleId:
          description: The role ID. If the role is a Soracom managed role, it will be in SRN (Soracom Resource Name) format.
          example: my-role
          type: string
        roleName:
          description: The role name. If the role is an operator managed role, it will be the same as `roleId`. If the role is a Soracom managed role, it will be the resource ID part of the SRN.
          example: my-role
          type: string
        updateDateTime:
          description: The update date and time of the role (UNIX time in seconds).
          example: 1722480600
          format: int64
          type: integer
      required:
      - createDateTime
      - roleId
      - updateDateTime
      type: object
    AttachRoleRequest:
      properties:
        roleId:
          description: 'The ID of the role to attach. For an operator managed role, specify the role ID (`roleId`) obtained from the [Role:listRoles API](#/Role/listRoles). For a Soracom managed role, specify the SRN (Soracom Resource Name).

            '
          type: string
      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