Rokwire Core Building Block

Core Building Block of the open-source Rokwire platform behind the official Illinois mobile app, handling users, accounts, profiles, organizations, and authentication/authorization. Source code is published under Apache 2.0.

OpenAPI Specification

university-of-illinois-urbana-champaign-rokwire-core.yaml Raw ↑
openapi: 3.0.3
info:
  title: Rokwire Core Building Block API
  description: Core Building Block API Documentation
  version: 1.62.0
servers:
- url: https://api.rokwire.illinois.edu/core
tags:
- name: Services
  description: Clients applications APIs.
- name: Admin
  description: Clients administration applications APIs.
- name: Enc
  description: APIs consumed by the Encryption building block.
- name: BBs
  description: APIs consumed by the platform building blocks.
- name: Third-Party Services
  description: APIs consumed by third-party services.
- name: UI
  description: Endpoints for HTML webpages
- name: System
  description: System APIs.
paths:
  /services/auth/login:
    post:
      tags:
      - Services
      summary: Login
      description: |
        Login using credentials to retrieve access token, refresh token, and user data
      requestBody:
        description: |
          User credential details and parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_Login'
            examples:
              email-sign_in:
                summary: Email - sign in
                value:
                  auth_type: email
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    email: [email protected]
                    password: test12345
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              email-sign_up:
                summary: Email - sign up
                value:
                  auth_type: email
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    email: [email protected]
                    password: test12345
                  params:
                    sign_up: true
                    confirm_password: test12345
                  preferences:
                    key1: value1
                    key2: value2
                  profile:
                    address: address
                    address2: address2
                    po_box: po box
                    city: city
                    birth_year: 1990
                    country: county
                    email: email
                    first_name: first name
                    last_name: last name
                    phone: "+000000000000"
                    photo_url: photo url
                    state: state
                    zip_code: zip code
                  privacy:
                    public: false
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              phone:
                summary: Phone - sign in OR sign up
                value:
                  auth_type: twilio_phone
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    phone: "+12223334444"
                    code: "123456"
                  preferences:
                    key1: value1
                    key2: value2
                  profile:
                    address: address
                    address2: address2
                    po_box: po box
                    city: city
                    birth_year: 1990
                    country: county
                    email: email
                    first_name: first name
                    last_name: last name
                    phone: "+000000000000"
                    photo_url: photo url
                    state: state
                    zip_code: zip code
                  privacy:
                    public: false
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              illinois_oidc:
                summary: Illinois OIDC login
                value:
                  auth_type: illinois_oidc
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds: https://redirect.example.com?code=ai324uith8gSEefesEguorgwsf43
                  params:
                    redirect_uri: https://redirect.example.com
                    pkce_verifier: w4iuhfq0u43hfq38ghn3gnSFSFiqp3ugnpugnqiprgUGNPINfsdoirpgia
                  preferences:
                    key1: value1
                    key2: value2
                  profile:
                    address: address
                    address2: address2
                    po_box: po box
                    city: city
                    birth_year: 1990
                    country: county
                    email: email
                    first_name: first name
                    last_name: last name
                    phone: "+000000000000"
                    photo_url: photo url
                    state: state
                    zip_code: zip code
                  privacy:
                    public: false
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              anonymous:
                summary: Anonymous login
                value:
                  auth_type: anonymous
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    anonymous_id: dbb5ea5d-6c6c-44b8-9952-7ebf0e844beb
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              username-sign_in:
                summary: Username - sign in
                value:
                  auth_type: username
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    username: testName
                    password: test12345
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
              username-sign_up:
                summary: Username - sign up
                value:
                  auth_type: username
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    username: testName
                    password: test12345
                  params:
                    sign_up: true
                    confirm_password: test12345
                  preferences:
                    key1: value1
                    key2: value2
                  profile:
                    address: address
                    address2: address2
                    po_box: po box
                    city: city
                    birth_year: 1990
                    country: county
                    email: email
                    first_name: first name
                    last_name: last name
                    phone: "+000000000000"
                    photo_url: photo url
                    state: state
                    zip_code: zip code
                  privacy:
                    public: false
                  device:
                    type: mobile
                    device_id: "5555"
                    os: Android
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/_shared_res_Login_Mfa'
                - $ref: '#/components/schemas/_shared_res_Login'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - invalid
                    - unverified
                    - verification-expired
                    - already-exists
                    - not-found
                    - internal-server-error
                    - shared-credential-unverified
                    description: |
                      - `invalid`: Invalid credentials
                      - `unverified`: Unverified credentials
                      - `verification-expired`: Credentials verification expired. The verification is restarted
                      - `already-exists`: Account already exists when `sign-up=true`
                      - `not-found`: Account could not be found when `sign-up=false`
                      - `internal-server-error`: An undefined error occurred
                      - `shared-credential-unverified`: The shared credential has not been verified yet
                  message:
                    type: string
  /services/auth/mfa:
    post:
      tags:
      - Services
      summary: MFA
      description: |
        Verify multi-factor authentication credentials to complete login
      parameters:
      - name: state
        in: query
        description: Login state
        required: false
        style: form
        explode: false
        schema:
          type: string
      requestBody:
        description: |
          MFA credentials and parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_Login_Mfa'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_Login'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/refresh:
    post:
      tags:
      - Services
      summary: Refresh
      description: |
        Refresh access token using a refresh token
      requestBody:
        description: |
          Refresh token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_Refresh'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_Refresh'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/login-url:
    post:
      tags:
      - Services
      summary: Get SSO login url
      description: |
        Retrieve a pre-formatted SSO login URL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_LoginUrl'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_LoginUrl'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/logout:
    post:
      tags:
      - Services
      summary: Logout
      description: |
        Logouts an account
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              required:
              - all_sessions
              type: object
              properties:
                all_sessions:
                  type: boolean
                  default: false
      responses:
        "200":
          description: Success
          content:
            text/plain:
              schema:
                type: string
                example: Success
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/credential/verify:
    get:
      tags:
      - Services
      summary: Validate verification code
      description: |
        Validates verification code to verify account ownership
      parameters:
      - name: id
        in: query
        description: Credential ID
        required: true
        style: form
        explode: false
        schema:
          type: string
      - name: code
        in: query
        description: Verification code
        required: true
        style: form
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
                example: Successfully verified code
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/credential/send-verify:
    post:
      tags:
      - Services
      summary: Send verification code to identifier
      description: |
        Sends verification code to identifier to verify account ownership
      requestBody:
        description: |
          Account information to be checked
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_credential_send-verify'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
                example: Successfully sent verification code
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/credential/forgot/initiate:
    post:
      tags:
      - Services
      summary: Initiate reset credential for a given identifier
      description: "Email auth type:\nSends the reset password code for a given identifier\nGenerates
        a reset code and expiry and sends it to the given identifier \n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_credential_forgot_initiate'
        required: true
      responses:
        "200":
          description: Success
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - unverified
                    - verification-expired
                    - internal-server-error
                    description: |
                      - `unverified`: Unverified credentials
                      - `verification-expired`: Credentials verification expired. The verification is restarted
                      - `internal-server-error`: An undefined error occurred
                  message:
                    type: string
  /services/auth/credential/forgot/complete:
    post:
      tags:
      - Services
      summary: Complete resetting forgotten credential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_credential_forgot_complete'
        required: true
      responses:
        "200":
          description: Success
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/credential/update:
    post:
      tags:
      - Services
      summary: Reset a credential from client application
      description: |
        Needs user auth token for authorization

        **Auth:** Requires token from direct user authentication from recent login
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_credential_update'
        required: true
      responses:
        "200":
          description: Success
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/verify-mfa:
    post:
      tags:
      - Services
      summary: MFA
      description: |
        Verify multi-factor authentication credentials to complete MFA registration
      requestBody:
        description: |
          MFA credentials and parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_Mfa'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/account/exists:
    post:
      tags:
      - Services
      summary: Check if an account already exists
      description: |
        Account exists checks if an account exists for the provided user identifier and auth type
      requestBody:
        description: |
          Account information to be checked
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_AccountCheck'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_AccountCheck'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/account/can-sign-in:
    post:
      tags:
      - Services
      summary: Check if a client can sign in
      description: |
        Checks if a client can sign in to an existing account for the provided user identifier and auth type
      requestBody:
        description: |
          Account information to be checked
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_AccountCheck'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_AccountCheck'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/account/can-link:
    post:
      tags:
      - Services
      summary: Check if a client can link an auth type
      description: |
        Checks if a client is able to link a new auth type to an account
      requestBody:
        description: |
          Account information to be checked
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_AccountCheck'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_shared_res_AccountCheck'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/account/auth-type/link:
    post:
      tags:
      - Services
      summary: Link credentials
      description: |
        Link credentials to an existing account

        **Auth:** Requires "authenticated" auth token
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_account_auth-type-link'
            examples:
              email-sign_up:
                summary: Email
                value:
                  auth_type: email
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    email: [email protected]
                    password: test12345
                  params:
                    confirm_password: test12345
              phone:
                summary: Phone
                value:
                  auth_type: twilio_phone
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds:
                    phone: "+12223334444"
              illinois_oidc:
                summary: Illinois OIDC
                value:
                  auth_type: illinois_oidc
                  app_type_identifier: edu.illinois.rokwire
                  org_id: 0a2eff20-e2cd-11eb-af68-60f81db5ecc0
                  api_key: 95a463e3-2ce8-450b-ba75-d8506b874738
                  creds: https://redirect.example.com?code=ai324uith8gSEefesEguorgwsf43
                  params:
                    redirect_uri: https://redirect.example.com
                    pkce_verifier: w4iuhfq0u43hfq38ghn3gnSFSFiqp3ugnpugnqiprgUGNPINfsdoirpgia
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_services_res_account_auth-type-link'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - invalid
                    - unverified
                    - verification-expired
                    - already-exists
                    - not-found
                    - internal-server-error
                    description: |
                      - `invalid`: Invalid credentials
                      - `unverified`: Unverified credentials
                      - `verification-expired`: Credentials verification expired. The verification is restarted
                      - `already-exists`: Auth type identifier already exists
                      - `not-found`: Account could not be found when `sign-up=false`
                      - `internal-server-error`: An undefined error occurred
                  message:
                    type: string
    delete:
      tags:
      - Services
      summary: Unlink credentials
      description: |
        Unlink credentials from an existing account

        **Auth:** Requires "authenticated" auth token
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_account_auth-type-unlink'
            examples:
              email:
                summary: Email
                value:
                  auth_type: email
                  app_type_identifier: edu.illinois.rokwire
                  identifier: [email protected]
              phone:
                summary: Phone
                value:
                  auth_type: twilio_phone
                  app_type_identifier: edu.illinois.rokwire
                  identifier: "+12223334444"
              illinois_oidc:
                summary: Illinois OIDC
                value:
                  auth_type: illinois_oidc
                  app_type_identifier: edu.illinois.rokwire
                  identifier: "123456789"
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_services_res_account_auth-type-link'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/authorize-service:
    post:
      tags:
      - Services
      summary: Authorize service
      description: |
        Authorize a third-party service and get a scoped access token that can be used to access its APIs

        **Auth:** Requires user auth token
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_services_req_authorize-service'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_services_res_authorize-service'
              examples:
                authorized:
                  summary: Service authorized
                  value:
                    access_token: string
                    token_type: Bearer
                    approved_scopes:
                    - string
                unauthorized:
                  summary: Service unauthorized
                  value:
                    service_reg:
                      service_id: string
                      service_account_id: string
                      host: string
                      pub_key:
                        key_pem: string
                        alg: string
                      name: string
                      description: string
                      info_url: string
                      logo_url: string
                      scopes:
                      - scope: string
                        required: true
                        explanation: string
                      first_party: true
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/auth/service-regs:
    get:
      tags:
      - Services
      summary: Get service registrations
      description: |
        Returns service registration records

        **Auth:** Requires auth token
      security:
      - bearerAuth: []
      parameters:
      - name: ids
        in: query
        description: A comma-separated list of service IDs to return registrations
          for
        required: true
        style: form
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceReg'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
  /services/accounts:
    get:
      tags:
      - Services
      summary: Finds accounts
      description: |
        Finds accounts using a set of optional search parameters

        **Auth:** Requires access token with `get_accounts`, `update_accounts`, or `all_accounts` permission
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        description: The maximum number of accounts to return
        required: false
        style: form
        explode: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The index of the first account to return
        required: false
        style: form
        explode: false
        schema:
          type: integer
      - name: account-id
        in: query
        description: The account ID
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: firstname
        in: query
        description: The account profile first name
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: lastname
        in: query
        description: The account profile last name
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: auth-type
        in: query
        description: The auth type
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: auth-type-identifier
        in: query
        description: The authentication type identifier
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: has-permissions
        in: query
        description: Account has permissions (permissions, roles, or groups) filter
        required: false
        style: form
        explode: false
        schema:
          type: boolean
      - name: permissions
        in: query
        description: A comma-separated list of permission names
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: role-ids
        in: query
        description: A comma-separated list of role IDs
        required: false
        style: form
        explode: false
        schema:
          type: string
      - name: group-ids
        in: query
        description: A comma-separated list of group IDs
        required: false
        style: form
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialAccount'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
    post:
      tags:
      - Services
      summary: Create admin account
      description: |
        Create a new admin account

        **Auth:** Requires auth token with `create_accounts` or `all_accounts` permission
      security:
      - bearerAuth: []
      requestBody:
        description: |
          User account details and parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_shared_req_CreateAccount'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialAccount'
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "500":
          description: Internal error
    put:
      tags:
      - Services
      summary: Update admin account
      description: |
        Update an existing admin account

        **Auth:** Requires auth token with `update_accounts` or `all_accounts` permission
      security:
      - bearerAuth: []
      requestBody:
        description: |
          User account details and parameters
        content:
          application/json:
            schema:
              $ref: '#/compone

# --- truncated at 32 KB (216 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-illinois-urbana-champaign/refs/heads/main/openapi/university-of-illinois-urbana-champaign-rokwire-core.yaml