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: 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