Phone

The MyAccount Phone API provides operations to enroll, update, and delete phone numbers. The API also provides utilities to create, view, and answer verification challenges.

API versioning

A valid API version in the Accept header is required to access the API. Current version: 1.0.0

Accept: application/json; okta-version=1.0.0

List all Phones
OAuth 2.0: okta.myAccount.phone.read

Lists the current user's phone information for all phones. Includes a collection of links for each phone describing the acceptable operations.

Responses
200

Example response

401

Unauthorized

get/idp/myaccount/phones
Request samples 
Response samples 
application/json;okta-version=1.0.0
[]
Create a Phone
OAuth 2.0: okta.myAccount.phone.manage
Creates an UNVERIFIED status phone for either the SMS or CALL method to the user's MyAccount setting


Request 
Request Body schema: application/json
required
object
Defines the phone number on the profile


 
phoneNumber
string
The newly added phone number


 
sendCode
boolean
 Default:  true
Whether to send a challenge to the newly added phone


 
method
string
The method of the challenge sent to the newly added phone. Applicable when sendCode is true.


 Enum: "SMS" "CALL"  
Responses 
201
Example response


400
Bad Request


401
Unauthorized


403
Forbidden


409
Conflict


500
Internal Server Error


post/idp/myaccount/phones
Request samples 
application/json
{
  • "profile": {
    • "phoneNumber": "+1(444)444-4444"
    },
  • "sendCode": true,
  • "method": "SMS"
}
Response samples 
application/json;okta-version=1.0.0
{}
Retrieve a Phone
OAuth 2.0: okta.myAccount.phone.read
Retrieves the current user's phone information by ID. Along with a collection of links describing the operations that can be performed to the phone.


Request 
path Parameters
id
required
string
The ID of the phone. Obtain the ID of the phone through GET /idp/myaccount/phones or POST /idp/myaccount/phones when adding a new phone.


 
 Example:  sms10ltpSdwXJCem80g4
Responses 
200
Example response


401
Unauthorized


404
Not Found


get/idp/myaccount/phones/{id}
Request samples 
Response samples 
application/json;okta-version=1.0.0
{}
Delete a Phone
OAuth 2.0: okta.myAccount.phone.manage
Deletes the current user's phone information by ID


Request 
path Parameters
id
required
string
The ID of the phone. Obtain the ID of the phone through GET /idp/myaccount/phones or POST /idp/myaccount/phones when adding a new phone.


 
 Example:  sms10ltpSdwXJCem80g4
Responses 
204
No Content


401
Unauthorized


403
Forbidden


404
Not Found


delete/idp/myaccount/phones/{id}
Request samples 
Response samples 
application/json;okta-version=1.0.0
{
  • "errorCode": "E0000015",
  • "errorSummary": "You do not have permission to access the feature you are requesting",
  • "errorLink": "E0000015",
  • "errorId": "oaeStOuPPxDRUm3PJhf-tL7bQ",
  • "errorCauses": [ ]
}
Send a Phone Challenge
OAuth 2.0: okta.myAccount.phone.manage
Sends a phone challenge using one of two methods: SMS or CALL. This request can also handle a resend challenge (retry).


Upon a successful challenge, the user receives a verification code by SMS or CALL. Send a POST request to the /idp/myaccount/phones/{id}/verify endpoint to use the verification code to verify the phone number. The verification code expires in five minutes.




Notes:


    

  • Sending requests to the /idp/myaccount/phones/{id}/challenge endpoint more often than once every 30 seconds, or at a rate that exceeds the rate limit rule configured by the admin, returns a 429 (Too Many Requests) error.
    • 





Request 
path Parameters
id
required
string
ID of the phone. Obtain the ID of the phone through GET /idp/myaccount/phones or POST /idp/myaccount/phones when adding a new phone.


 
 Example:  sms18vtfKgzqDhNqP0g4
Request Body schema: application/json
method
required
string
The method with which the challenge should be sent


 Enum: "SMS" "CALL"  
retry
boolean
 Default:  false
Indicates whether this is a normal challenge or retry


 
Responses 
200
Example response after challenging a phone


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


500
Internal Server Error


post/idp/myaccount/phones/{id}/challenge
Request samples 
application/json
{
  • "method": "SMS"
}
Response samples 
application/json;okta-version=1.0.0
{}
Verify a Phone Challenge
OAuth 2.0: okta.myAccount.phone.manage
Verifies the phone number with the verification code that the user receives through SMS or CALL. The phone number is active upon a successful verification.




Notes:


    

  • Sending requests to the /idp/myaccount/phones/{id}/verify endpoint at a rate that exceeds the rate limit rule configured by the admin returns a 429 (Too Many Requests) error.
    • 





Request 
path Parameters
id
required
string
The phone ID. Obtain the ID of the phone through GET /idp/myaccount/phones or POST /idp/myaccount/phones when adding a new phone.


 
 Example:  sms18vtfKgzqDhNqP0g4
Request Body schema: application/json
verificationCode
required
string <password> 
A six-digit verification code that the user receives through SMS or CALL


 
Responses 
204
No Content


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


409
Conflict


post/idp/myaccount/phones/{id}/verify
Request samples 
application/json
{
  • "verificationCode": "048284"
}
Response samples 
application/json;okta-version=1.0.0
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: Method",
  • "errorLink": "E0000001",
  • "errorId": "oaejUwz8U5FQ_SyggQwz1kC3w",
  • "errorCauses": [
    • {
      }
    ]
}