OktaUserAPI.yaml

# To load into Swagger Editor / Preview UI, go to:
# https://editor.swagger.io/#/?import=https://gabrielsroka.github.io/OktaUserAPI.yaml
swagger: '2.0'
info:
  title: Okta Users API
  version: '1'
schemes: [https]
# Replace ORG with your org. Use okta.com or oktapreview.com
host: ORG.okta.com
# host: ORG.oktapreview.com
basePath: /api/v1
consumes:
  - application/json
produces:
  - application/json
paths:
  /users:
    post:
      description: Creates a new user in your Okta organization with or without credentials.
      parameters:
        - name: activate
          in: query
          type: boolean
          default: true
        - name: provider
          in: query
          type: boolean
        - $ref: "#/parameters/body"
      responses:
        200:
          $ref: "#/responses/user"
    get:
      description: List Users
      parameters:
        - name: q
          in: query
          type: string
          description: Searches `firstName`, `lastName`, and `email` properties of users for matching value. Does not support pagination.
        - name: limit
          in: query
          type: integer
          default: 200
        - name: filter
          in: query
          type: string
      responses:
        200:
          description: An array of users
          schema:
            type: array
            items:
              $ref: "#/definitions/User"
          headers:
            Link:
              description: <url>; rel="(self|next|prev)"
              type: array
              items:
                type: string  
  /users/{id}:
    parameters:
      - $ref: "#/parameters/id"
    get:
      description: See [Get User](https://developer.okta.com/docs/api/resources/users#get-user). Supports CORS.
      responses:
        200:
          $ref: "#/responses/user"
        404:
          $ref: "#/responses/notFound"
    put:
      description: See [Update User and delete unspecified properties](https://developer.okta.com/docs/api/resources/users#update-profile)
      parameters:
        - $ref: "#/parameters/body"
      responses:
        200:
          $ref: "#/responses/user"
    post:
      description: See [Update User with partial update](https://developer.okta.com/docs/api/resources/users#update-profile)
      parameters:
        - $ref: "#/parameters/body"
      responses:
        200:
          $ref: "#/responses/user"
definitions:
  User:
    type: object
    properties:
      id:
        type: string
      status:
        type: string
        enum: [STAGED, PROVISIONED, ACTIVE, RECOVERY, LOCKED_OUT, PASSWORD_EXPIRED, DEPROVISIONED]
      created:
        type: string
        format: date-time
      activated:
        type: string
        format: date-time
      statusChanged:
        type: string
        format: date-time
      lastLogin:
        type: string
        format: date-time
      lastUpdated:
        type: string
        format: date-time
      profile:
        $ref: "#/definitions/Profile"
      credentials:
        $ref: "#/definitions/Credentials"
  Profile:
    type: object
    properties:
      login:
        type: string
        format: email
      email:
        type: string
        format: email
      firstName:
        type: string
      lastName:
        type: string
  Credentials:
    type: object
    properties:
      password:
        $ref: "#/definitions/Password"
      recovery_question:
        $ref: "#/definitions/RecoveryQuestion"
      provider:
        $ref: "#/definitions/Provider"
  Password:
    title: Password
    type: object
    properties:
      value:
        type: string
  RecoveryQuestion:
    type: object
    properties:
      question:
        type: string
      answer:
        type: string
  Provider:
    type: object
    properties:
      type:
        type: string
        enum: [OKTA, ACTIVE_DIRECTORY, LDAP, FEDERATION, SOCIAL]
      name:
        type: string
  body:
    type: object
    properties:
      profile:
        $ref: "#/definitions/Profile"
      credentials:
        $ref: "#/definitions/Credentials"
  Error:
    externalDocs:
      url: https://developer.okta.com/docs/api/getting_started/design_principles#errors
    type: object
    properties:
      errorCode:
        type: string
      errorSummary:
        type: string
      errorLink:
        type: string
      errorId:
        type: string
      errorCauses:
        type: array
        items:
          type: object
          properties:
            errorSummary:
              type: string
parameters:
  id:
    name: id
    in: path
    type: string
    required: true
    description: "`id`, `login`, login `shortname` (as long as it is unambiguous), or `me`"
  body:
    name: "-"
    in: body
    required: true
    schema:
      $ref: "#/definitions/body"
responses:
  user:
    description: A [user](https://developer.okta.com/docs/api/resources/users#user-model)
    schema:
      $ref: "#/definitions/User"
    headers:
      X-Rate-Limit-Limit:
        type: integer
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: integer
  notFound:
    description: Not found
    schema:
      $ref: "#/definitions/Error"
securityDefinitions:
  SSWS:
    type: apiKey
    name: Authorization
    in: header
    description: |
      See [Authentication](https://developer.okta.com/docs/api/getting_started/design_principles#authentication). Example:
      
      `SSWS {apikey}`
security:
  - SSWS: []