JumpCloud Push Verification API

openapi: 3.2.0
info:
  contact:
    name: JumpCloud Support
    url: https://jumpcloud.com/support/contact-jumpcloud-support
  description: '# Overview


    JumpCloud''s V2 API. This set of endpoints allows JumpCloud customers to manage objects, groupings and mappings and interact with the JumpCloud Graph. > **Note:** See JumpCloud Data Centers: Login URLs and Service Endpoints to learn more. ## API Best Practices


    Read the linked Help Article below for guidance on retrying failed requests to JumpCloud''s REST API, as well as best practices for structuring subsequent retry requests. Customizing retry mechanisms based on these recommendations will increase the reliability and dependability of your API calls. Covered topics include:

    1. Important Considerations

    2. Supported HTTP Request Methods

    3. Response codes

    4. API Key rotation

    5. Paginating

    6. Error handling

    7. Retry rates


    JumpCloud Help Center - API Best Practices


    # Directory Objects


    This API offers the ability to interact with some of our core features; otherwise known as Directory Objects. The Directory Objects are:


    * Commands

    * Policies

    * Policy Groups

    * Applications

    * Systems

    * Users

    * User Groups

    * System Groups

    * Radius Servers

    * Directories: Office 365, LDAP,G-Suite, Active Directory

    * Duo accounts and applications. The Directory Object is an important concept to understand in order to successfully use JumpCloud API. ## JumpCloud Graph


    We''ve also introduced the concept of the JumpCloud Graph along with Directory Objects. The Graph is a powerful aspect of our platform which will enable you to associate objects with each other, or establish membership for certain objects to become members of other objects. Specific `GET` endpoints will allow you to traverse the JumpCloud Graph to return all indirect and directly bound objects in your organization. | !alt text |

    |:--:|

    | **This diagram highlights our association and membership model as it relates to Directory Objects.** |


    # API Key


    ## Access Your API Key


    To locate your API Key:


    1. Log into the JumpCloud Admin Console. 2. Go to the username drop down located in the top-right of the Console. 3. Retrieve your API key from API Settings. ## API Key Considerations


    This API key is associated to the currently logged in administrator. Other admins will have different API keys. **WARNING** Please keep this API key secret, as it grants full access to any data accessible via your JumpCloud console account. You can also reset your API key in the same location in the JumpCloud Admin Console. ## Recycling or Resetting Your API Key


    In order to revoke access with the current API key, simply reset your API key. This will render all calls using the previous API key inaccessible. Your API key will be passed in as a header with the header name "x-api-key". ```bash

    curl -H "x-api-key: [YOUR_API_KEY_HERE]" "https://console.jumpcloud.com/api/v2/systemgroups"

    ```


    # System Context


    * Introduction

    * Supported endpoints

    * Response codes

    * Authentication

    * Additional examples

    * Third party


    ## Introduction


    JumpCloud System Context Authorization is an alternative way to authenticate with a subset of JumpCloud''s REST APIs. Using this method, a system can manage its information and resource associations, allowing modern auto provisioning environments to scale as needed. **Notes:**


    * The following documentation applies to Linux Operating Systems only. * Systems that have been automatically enrolled using Apple''s Device Enrollment Program (DEP) or systems enrolled using the User Portal install are not eligible to use the System Context API to prevent unauthorized access to system groups and resources. If a script that utilizes the System Context API is invoked on a system enrolled in this way, it will display an error. ## Supported Endpoints


    JumpCloud System Context Authorization can be used in conjunction with Systems endpoints found in the V1 API and certain System Group endpoints found in the v2 API.'
  title: JumpCloud Push Verification API
  version: '2.0'
servers:
- url: https://console.jumpcloud.com/api/v2
  description: United States (US)
  x-jc-region: us
- url: https://console.eu.jumpcloud.com/api/v2
  description: European Union (EU)
  x-jc-region: eu
- url: https://console.in.jumpcloud.com/api/v2
  description: India (IN)
  x-jc-region: in
tags:
- name: Push Verification
paths:
  /pushendpoints/verifications/{verificationId}:
    get:
      summary: Get Push Verification status
      description: Endpoint for retrieving a verification push notification status
      operationId: PushVerifications_Get
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jumpcloud.auth.PushVerification'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
      tags:
      - Push Verification
      security:
      - x-api-key: []
      x-dynamic-gateway: true
      x-scopes:
      - protect
      x-codeSamples:
      - lang: Shell
        source: "curl --request GET \\\n  --url https://console.jumpcloud.com/api/v2/pushendpoints/verifications/{verificationId} \\\n  --header 'x-api-key: REPLACE_KEY_VALUE'"
      - lang: Python
        source: 'import requests


          url = "https://console.jumpcloud.com/api/v2/pushendpoints/verifications/{verificationId}"


          headers = {"x-api-key": "REPLACE_KEY_VALUE"}


          response = requests.request("GET", url, headers=headers)


          print(response.text)'
      - lang: Powershell
        source: '$headers=@{}

          $headers.Add("x-api-key", "REPLACE_KEY_VALUE")

          $response = Invoke-RestMethod -Uri ''https://console.jumpcloud.com/api/v2/pushendpoints/verifications/{verificationId}'' -Method GET -Headers $headers'
  /users/{userId}/pushendpoints/{pushEndpointId}/verify:
    post:
      summary: Send Push Verification message
      description: Endpoint for sending a verification push notification
      operationId: PushVerifications_Start
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jumpcloud.auth.PushVerification'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: byte
      - name: pushEndpointId
        in: path
        required: true
        schema:
          type: string
          format: byte
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
              title: SendVerificationPushRequest represents a create request
        required: true
      tags:
      - Push Verification
      security:
      - x-api-key: []
      x-dynamic-gateway: true
      x-scopes:
      - protect
      x-codeSamples:
      - lang: Shell
        source: "curl --request POST \\\n  --url https://console.jumpcloud.com/api/v2/users/{userId}/pushendpoints/{pushEndpointId}/verify \\\n  --header 'content-type: application/json' \\\n  --header 'x-api-key: REPLACE_KEY_VALUE' \\\n  --data '{\"message\":\"string\"}'"
      - lang: Python
        source: "import requests\n\nurl = \"https://console.jumpcloud.com/api/v2/users/{userId}/pushendpoints/{pushEndpointId}/verify\"\n\npayload = {\"message\": \"string\"}\nheaders = {\n    \"x-api-key\": \"REPLACE_KEY_VALUE\",\n    \"content-type\": \"application/json\"\n}\n\nresponse = requests.request(\"POST\", url, json=payload, headers=headers)\n\nprint(response.text)"
      - lang: Powershell
        source: '$headers=@{}

          $headers.Add("x-api-key", "REPLACE_KEY_VALUE")

          $headers.Add("content-type", "application/json")

          $response = Invoke-RestMethod -Uri ''https://console.jumpcloud.com/api/v2/users/{userId}/pushendpoints/{pushEndpointId}/verify'' -Method POST -Headers $headers -ContentType ''application/json'' -Body ''{"message":"string"}'''
components:
  schemas:
    jumpcloud.auth.PushVerification:
      type: object
      properties:
        confirmationCode:
          type: string
        expiresAt:
          type: string
          format: date-time
        failureStatus:
          $ref: '#/components/schemas/google.rpc.Status'
        id:
          type: string
        initiatedAt:
          type: string
          format: date-time
        pushEndpointId:
          type: string
          format: byte
        status:
          $ref: '#/components/schemas/jumpcloud.auth.PushVerification.Status'
        userObjectId:
          type: string
          format: byte
    Error:
      title: Error
      type: object
      x-examples: {}
      description: ''
      properties:
        code:
          format: int32
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message
        status:
          type: string
          description: HTTP status description
    google.rpc.Status:
      properties:
        code:
          type: integer
          format: int32
          description: 'The status code, which should be an enum value of

            [google.rpc.Code][google.rpc.Code].'
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
          description: 'A list of messages that carry the error details.  There is a common set of

            message types for APIs to use.'
        message:
          type: string
          description: 'A developer-facing error message, which should be in English. Any

            user-facing error message should be localized and sent in the

            [google.rpc.Status.details][google.rpc.Status.details] field, or localized

            by the client.'
      description: 'The `Status` type defines a logical error model that is suitable for

        different programming environments, including REST APIs and RPC APIs. It is

        used by [gRPC](https://github.com/grpc). Each `Status` message contains

        three pieces of data: error code, error message, and error details.


        You can find out more about this error model and how to work with it in the

        [API Design Guide](https://cloud.google.com/apis/design/errors).'
      type:
      - object
      - 'null'
    google.protobuf.Any:
      type: object
      properties:
        '@type':
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
      additionalProperties: {}
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n\nExample 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\nExample 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    jumpcloud.auth.PushVerification.Status:
      type: string
      enum:
      - SENT
      - ACCEPTED
      - EXPIRED
      - DENIED
      - ERRORED
      default: SENT
  securitySchemes:
    x-api-key:
      description: API key used to authenticate requests.
      in: header
      name: x-api-key
      type: apiKey
x-tagGroups:
- name: API Reference
  tags:
  - Access Requests
  - Access Risk Settings
  - Active Directory
  - Administrators
  - Agent Groups
  - Agents
  - Aggregated Policy Stats
  - App Catalog
  - Apple MDM
  - Applications
  - Assets
  - Authentication Policies
  - Bulk Job Requests
  - Commands
  - Custom Emails
  - Directories
  - Directory Insights
  - Duo
  - Email Subscriptions
  - FeatureTrials
  - G Suite
  - G Suite Import
  - GCEP
  - Google EMM
  - Graph
  - Groups
  - IP Lists
  - Identity Providers
  - Identity Risk
  - Image
  - LDAP Servers
  - Logos
  - Managed Service Provider
  - Microsoft MDM
  - Monitoring and Alerting
  - Notifications Channels
  - Object Storage
  - Office 365
  - Office 365 Import
  - Organization Feature Settings
  - Organizations
  - Password Manager
  - Password Policy
  - Password Vault
  - PasswordManagerItem
  - Policies
  - Policy Group Associations
  - Policy Group Members & Membership
  - Policy Group Templates
  - Policy Groups
  - Policytemplates
  - Privileged Access
  - Providers
  - Push Verification
  - RADIUS Servers
  - Reports
  - Roles
  - Rules
  - SCIM Import
  - SaaS App Management
  - Samba Domains
  - Sample Data
  - Saved Views
  - Scope Groups
  - Service Accounts
  - Slack Notifications
  - Software Apps
  - Subscriptions
  - System Group Associations
  - System Group Members & Membership
  - System Groups
  - System Insights
  - Systems
  - Systems Organization Settings
  - Translation Rules
  - User Group Associations
  - User Group Members & Membership
  - User Groups
  - Users
  - Webhook Notifications
  - Webhook Notifications Channels
  - Workday Import
  - Workflows
  - fde
  - mdm
x-scopes:
- accessmanagement
- accessmanagement.readonly
- accessrequest
- accessrequest.readonly
- administratorLinks
- administrators
- administrators.readonly
- agents
- agents.create
- agents.credentials.delete
- agents.credentials.readonly
- agents.credentials.update
- agents.delete
- agents.readonly
- agents.state
- agents.state.activate
- agents.state.suspend
- agents.update
- anonymous
- applications
- applications.readonly
- applications.update
- assets
- assets.readonly
- associations
- associations.applications
- associations.applications.readonly
- associations.authn
- associations.authn.readonly
- associations.commands
- associations.commands.readonly
- associations.directories
- associations.directories.readonly
- associations.groups
- associations.groups.readonly
- associations.radius
- associations.radius.readonly
- associations.readonly
- associations.self
- associations.systems
- associations.systems.readonly
- associations.users
- associations.users.readonly
- authn
- authn.readonly
- billing
- commandrunner.legacy
- commands
- commands.readonly
- directories
- directories.readonly
- directoryinsights.readonly
- groups
- groups.readonly
- groups.self
- healthmonitoring.alerts
- healthmonitoring.alerts.readonly
- healthmonitoring.rules
- healthmonitoring.rules.readonly
- identityrisk
- identityrisk.readonly
- mdm
- mdm.readonly
- mfa
- mfa.readonly
- notifications.channels
- notifications.channels.readonly
- notifications.subscriptions
- notifications.subscriptions.readonly
- organizations
- organizations.billing
- organizations.readonly
- pam
- pam.backup
- pam.blocking-rules.create
- pam.blocking-rules.delete
- pam.blocking-rules.readonly
- pam.blocking-rules.update
- pam.jump-servers.create
- pam.jump-servers.delete
- pam.jump-servers.readonly
- pam.jump-servers.update
- pam.manage-all-privileged-resources
- pam.overview
- pam.privileged-credentials.create
- pam.privileged-credentials.delete
- pam.privileged-credentials.readonly
- pam.privileged-credentials.update
- pam.privileged-databases.create
- pam.privileged-databases.delete
- pam.privileged-databases.readonly
- pam.privileged-databases.update
- pam.privileged-servers.create
- pam.privileged-servers.delete
- pam.privileged-servers.readonly
- pam.privileged-servers.update
- pam.privileged-websites.create
- pam.privileged-websites.delete
- pam.privileged-websites.readonly
- pam.privileged-websites.update
- pam.readonly
- pam.resource-managers.create
- pam.resource-managers.delete
- pam.resource-managers.readonly
- pam.resource-managers.update
- pam.session-history
- pam.user-groups.create
- pam.user-groups.delete
- pam.user-groups.readonly
- pam.user-groups.update
- partners
- partners.readonly
- passwordmanager
- passwordmanager.readonly
- protect
- providers
- providers.readonly
- radius
- radius.readonly
- reports
- reports.readonly
- roles
- roles.readonly
- saas
- saas.readonly
- serviceaccounts
- serviceaccounts.readonly
- subscriptions.readonly
- support
- support.readonly
- systeminsights.readonly
- systems
- systems.management
- systems.readonly
- transfer
- users
- users.create
- users.password
- users.password.expire
- users.properties
- users.properties.update
- users.readonly
- users.self
- users.state
- users.state.delete
- users.state.readonly
- users.state.unlock
- users.state.update
- workflows
- workflows.readonly