Skip to content

Instantly share code, notes, and snippets.

@karlmcguinness-okta

karlmcguinness-okta/gist:b53c60f5847b0e35cdfb

Forked from srinivasanagandla-okta/gist:156bc8b8ceac624b6897
Last active November 16, 2022 22:21
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save karlmcguinness-okta/b53c60f5847b0e35cdfb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save karlmcguinness-okta/b53c60f5847b0e35cdfb to your computer and use it in GitHub Desktop.
Download ZIP
Okta Verify Push Auth API
Raw
gistfile1.md

Enroll via Auth API

Primary Authentication

POST https://your-domain.okta.com/api/v1/authn

{
  "username": "isaac@example.org",
  "password": "GoAw@y123",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "context": {
    "ipAddress": "192.168.12.11",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)",
    "deviceToken": "26q43Ak9Eh04p7H6Nnx0m69JqYOrfVBY"
  }
}
{
  "stateToken": "00Z20ZhXVrmyR3z8R-m77BvknHyckWCy5vNwEA6huD",
  "expiresAt": "2014-11-02T23:44:41.736Z",
  "status": "MFA_ENROLL",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": [
      {
        "factorType": "push",
        "provider": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://your-domain.okta.com/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      }
    ]
  },
  "_links": {
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll Factor

POST https://your-domain.okta.com/api/v1/authn/factors

{
  "stateToken": "00Z20ZhXVrmyR3z8R-m77BvknHyckWCy5vNwEA6huD",
  "factorType": "push",
  "provider": "OKTA"
}
{
  "stateToken": "00lT7DEzQaeP6mv1_y3pdXjNEONzk83mXX-yhgEdVQ",
  "expiresAt": "2014-11-03T00:46:09.700Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {

      },
      "_embedded": {
        "activation": {
          "deviceActivationToken": "I17JQoOqbYOPH_lMWK5F",
          "_links": {
            "qrcode": {
              "href": "https://your-domain.okta.com/api/v1/users/00uoy3CXZHSMMJPHYXXP/factors/opfh52xcuft3J4uZc0g3/qr/00Mb0zqhJQohwCDkB2wOifajAsAosEAXvDwuCmsAZs",
              "type": "image/png"
            }
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://nag.okta1.com:80/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Activate Factor

POST https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate

{
  "stateToken": "00wlafXU2GV9I3tNvDNkOA1thqM5gDwCOgHID_-Iej"
}
HTTP/1.1 202 Accepted

{
  "stateToken": "00lT7DEzQaeP6mv1_y3pdXjNEONzk83mXX-yhgEdVQ",
  "expiresAt": "2014-11-03T00:46:09.700Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {

      },
      "_embedded": {
        "activation": {
          "deviceActivationToken": "I17JQoOqbYOPH_lMWK5F",
          "_links": {
            "qrcode": {
              "href": "https://your-domain.okta.com/api/v1/users/00uoy3CXZHSMMJPHYXXP/factors/opfh52xcuft3J4uZc0g3/qr/00Mb0zqhJQohwCDkB2wOifajAsAosEAXvDwuCmsAZs",
              "type": "image/png"
            }
          }
        }
      }
    }
  },  
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://nag.okta1.com:80/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Poll for Activation

POST https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate

{
  "stateToken": "00wlafXU2GV9I3tNvDNkOA1thqM5gDwCOgHID_-Iej"
}
HTTP/1.1 202 Accepted

{
  "stateToken": "00lT7DEzQaeP6mv1_y3pdXjNEONzk83mXX-yhgEdVQ",
  "expiresAt": "2014-11-03T00:46:09.700Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {

      },
      "_embedded": {
        "activation": {
          "deviceActivationToken": "I17JQoOqbYOPH_lMWK5F",
          "_links": {
            "qrcode": {
              "href": "https://your-domain.okta.com/api/v1/users/00uoy3CXZHSMMJPHYXXP/factors/opfh52xcuft3J4uZc0g3/qr/00Mb0zqhJQohwCDkB2wOifajAsAosEAXvDwuCmsAZs",
              "type": "image/png"
            }
          }
        }
      }
    }
  },  
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://nag.okta1.com:80/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Complete Enrollment

POST https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate

{
  "stateToken": "00wlafXU2GV9I3tNvDNkOA1thqM5gDwCOgHID_-Iej"
}
HTTP/1.1 200 OK

{
  "expiresAt": "2014-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify via Auth API

Primary Authentication

POST https://your-domain.okta.com/api/v1/authn

{
  "username": "isaac@example.org",
  "password": "GoAw@y123",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "context": {
    "ipAddress": "192.168.12.11",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)",
    "deviceToken": "26q43Ak9Eh04p7H6Nnx0m69JqYOrfVBY"
  }
}
{
  "stateToken": "00Z20ZhXVrmyR3z8R-m77BvknHyckWCy5vNwEA6huD",
  "expiresAt": "2014-11-02T23:44:41.736Z",
  "status": "MFA_REQUIRED",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": [
      {
        "id": "opfh52xcuft3J4uZc0g3",
        "factorType": "push",
        "provider": "OKTA",
        "profile": {
          "platform": "IOS",
          "deviceType": "SMARTPHONE",
          "name": "karl iPhone",
          "version": "8.1"
        },
        "_links": {
          "verify": {
            "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      }
    ]
  },
  "_links": {
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Verify

POST https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify

{
  "stateToken": "00wlafXU2GV9I3tNvDNkOA1thqM5gDwCOgHID_-Iej"
}
HTTP/1.1 202 Accepted

{
  "stateToken": "00Z20ZhXVrmyR3z8R-m77BvknHyckWCy5vNwEA6huD",
  "expiresAt": "2014-11-02T23:44:41.736Z",
  "status": "MFA_CHALLENGE",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "factorResult": "WAITING"
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {
        "platform": "IOS",
        "deviceType": "SMARTPHONE",
        "name": "karl iPhone",
        "version": "8.1"
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://your-domain.okta.com/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://your-domain.okta.com/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "push",
        "href": "https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
}

Poll for Verification Complete

POST https://your-domain.okta.com/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify

{
  "stateToken": "00wlafXU2GV9I3tNvDNkOA1thqM5gDwCOgHID_-Iej"
}
HTTP/1.1 200 OK

{
  "expiresAt": "2014-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "profile": {
        "login": "isaac@example.org",
        "firstName": "Isaac",
        "lastName": "Brock",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Enroll Factor API:

Request

POST {{url}}/api/v1/users/{{userId}}/factors

{
  "factorType": "push",
  "provider": "OKTA"
}

Response

{
  "id": "opfh52xcuft3J4uZc0g3",
  "factorType": "push",
  "provider": "OKTA",
  "status": "PENDING_ACTIVATION",
  "created": "2015-04-01T15:57:32.000Z",
  "lastUpdated": "2015-04-01T15:57:32.000Z",
  "profile": {

  },
  "_links": {
    "activate": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "self": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "user": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "qrcode": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/qr/00CnAHABTzHh9hjEij9qcteMrOoeFLK6evHruUH7p9",
      "type": "image/png"
    }
  },
  "_embedded": {
    "activation": {
      "deviceActivationToken": "I17JQoOqbYOPH_lMWK5F"
    }
  }
}

After Activation:

##Request

GET {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}?expand=device

##Response:

{
  "id": "opfh52xcuft3J4uZc0g3",
  "factorType": "push",
  "provider": "OKTA",
  "status": "ACTIVE",
  "created": "2015-04-01T15:57:32.000Z",
  "lastUpdated": "2015-04-01T16:04:56.000Z",
  "profile": {
    "platform": "IOS",
    "deviceType": "SMARTPHONE",
    "name": "karl iPhone",
    "version": "8.1"
  },
  "_links": {
    "self": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "verify": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },    
    "user": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "device": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/devices/mbdg6uYNMQTFLDUUICST",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

###Gaps/Issues:

  1. Add "reset" link

Start Challenge:

Request

POST {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}/verify

Response

HTTP/1.1 202 Accepted
Location: https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify/mst1eiHghhPxf0yhp0g3

{
  "factorResult": "WAITING",
  "_links": {
    "poll": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify/mst1eiHghhPxf0yhp0g",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "cancel": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify/mst1eiHghhPxf0yhp0g",
      "hints": {
        "allow": [
          "DELETE"
        ]
      }
    }
  }
}

Poll

Request:

GET {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}/verify/{{transactionId}}

Response:

{
  "factorResult": "WAITING",
  "_links": {
    "poll": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify/mst1eiHghhPxf0yhp0g",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "cancel": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify/mst1eiHghhPxf0yhp0g",
      "hints": {
        "allow": [
          "DELETE"
        ]
      }
    }
  }
}

After Auth is Approved on Device:

Request:

GET {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}/verify/{{transactionId}}

Response:

{
  "factorResult": "SUCCESS"
}

When timed-out:

Request:

**GET {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}/verify/{{transactionId}}

Response:

{
  "factorResult": "TIMEOUT",
  "_links": {
    "verify": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "factor": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    }
  }
}

When Rejected:

Request:

**GET {{url}}/api/v1/users/{{userId}}/factors/{{factorId}}/verify/{{transactionId}}

Response:

{
  "factorResult": "REJECTED",
  "_links": {
    "verify": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "factor": {
      "href": "https://nag.okta1.com:80/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    }
  }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment