3 Step Enrollment

gistfile1.md

Enroll, Activate, Verify Flow

Enroll factor without initiating activation

Request

POST /api/v1/users/00TmqQCMPRSYHBDHVWAN/factors?activate=false HTTP/1.1
Host: your-subdomain.okta.com
Authorization: SSWS yourtoken
Accept: application/json
Content-Type: application/json

{
    "factorType": "sms",
    "provider" : "okta",
    "deviceType": "mobile",
    "profile": {
        "deviceName": "My Office Phone",
        "phoneNumber": "+1 408-123-4567"
    }
}

Response

HTTP/1.1 301 MOVED PERMANENTLY
Location: http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO
Content-Type: application/json

{
    "id" : "00ud4tVDDXYVKPXKVLCO",
    "factorType" : "sms",
    "status" : "ENROLLED",
    "created" : "2013-06-24T16:39:18.000Z",
    "activated" : "null",
    "lastVerification" : "null",
    "lastUpdated" : "2013-07-02T21:36:25.344Z",
    "profile": {
              "deviceName" : "My Office Phone"
              "phoneNumber": "+1 408-123-4567"
           },
     "_links": {
        "self": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO",
            "hints": { 
                "allow": ["GET", "PUT", "DELETE"]
            }
        },
        "next" : {
            "name" : "activate",
             "href" : "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/activate",
            "hints": {
                "allow": ["POST"]
            }
        },
        "activate": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/activate",
            "hints": {
                "allow": ["POST"]
            }
        },
        "user": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN",
            "hints": {
                "allow": ["GET"]
            }
        },
        "provider": {
            "href": "http://rain.okta1.com:1802/api/v1/factors/providers/okta",
            "hints": {
                "allow": ["GET"]
            }
         }
}

Start Activation

Request

POST /api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/activate HTTP/1.1
Host: your-subdomain.okta.com
Authorization: SSWS yourtoken
Accept: application/json

Response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
    "status" : "PENDING_VERIFICATION",
    "expiresAt" : "2014-03-17T17:44:19.000Z",
    "nextAction" : "verify",
    "_embedded" : {
         "verify" : {
              "type" : "passcode",
              "count" : "1"
          }
     },
    "_links": {
        "next" : {
             "name":"verify",
              "href" : "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/verify",
            "hints": { 
                "allow": ["POST"]
            },
         },
        "factor": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO",
            "hints": { 
                "allow": ["GET"]
            },
        "verify": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/verify",
            "hints": { 
                "allow": ["POST"]
            },
       "resend": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/activate?resend=true",
            "hints": { 
                "allow": ["POST"]
            }
        }
}

Verify Factor

Request

POST /api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/verify HTTP/1.1
Host: your-subdomain.okta.com
Authorization: SSWS yourtoken
Accept: application/json
Content-Type: application/json

{
    "activationCode" : 738402
}

Response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
    "id": "00ud4tVDDXYVKPXKVLCO",
    "verificationStatus": "SUCCESS",
    "status": "ACTIVE",
    "_links": {
        "factor": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO",
            "hints": { 
                "allow": ["GET"]
                }
           }
      }
}

Get/Poll Status of the SMS Factor

GET /api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO HTTP/1.1
Host: your-subdomain.okta.com
Authorization: SSWS yourtoken
Accept: application/json
Content-Type: application/json

Response

{
    "id" : "00ud4tVDDXYVKPXKVLCO",
    "factorType" : "sms",
    "status" : "ACTIVE",
    "created" : "2013-06-24T16:39:18.000Z",
    "activated" : "2013-06-24T16:40:18.000Z",
    "lastVerification" : "2013-06-24T16:41:18.000Z",
    "lastUpdated" : "2013-06-24T16:41:18.000Z",
    "profile": {
          "deviceName": "My Office Phone",
          "phoneNumber": "+1 408-123-4567"
     },
     "_links": {
        "self": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO",
            "hints": { 
                "allow": ["GET", "PUT", "DELETE"]
            }
        },
        "deactivate": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN/factors/00ud4tVDDXYVKPXKVLCO/lifecycle/deactivate",
            "hints": {
                "allow": ["POST"]
            }
        },
        "user": {
            "href": "http://rain.okta1.com:1802/api/v1/users/00TmqQCMPRSYHBDHVWAN",
            "hints": {
                "allow": ["GET"]
            }
        },
        "provider": {
            "href": "http://rain.okta1.com:1802/api/v1/factors/providers/00TmqQCMPRSYHBDHVWAN",
            "hints": {
                "allow": ["GET"]
            }
         }    
}