Clients applications APIs.
openapi: 3.0.3
info:
title: Rokwire Core Building Block Admin Services 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.
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: test@example.com
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: test@example.com
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: test@example.com
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: test@example.com
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: '#/components/schemas/_shared_req_UpdateAccount'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PartialAccount'
'400':
description: Bad request
'401
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-illinois-urbana-champaign/refs/heads/main/openapi/university-of-illinois-urbana-champaign-services-api-openapi.yml