Multi-factor authentication

Use the following multi-factor authentication API operations to configure and manage multi-factor authentication settings for Rackspace Cloud Accounts. For more information, see Using multi-factor authentication.

Add a mobile phone
Send verification code to phone
Verify a mobile phone
List multi-factor mobile phone by device ID
List multi-factor phones for user
Remove phone from account
Create an OTP device
Verify an OTP device
List the specified OTP device
Get the OTP devices for a specified account
Remove a specified OTP device from a user account
Update multi-factor authentication settings on account
Generate bypass codes
Update domain enforcement setting
Remove mutlifactor authentication from account

ℹ️
Note

Users can always use the MFA services on themselves.

Users with the identity:service-admin role can preform MFA operations for users with the identity:admin role, users with the identity:user-admin role, and sub-users.

Users with the identity:admin role can preform MFA operations for users with the identity:user-admin role and sub-users.

Users with the identity:user-admin or identity:user-manage role can preform MFA operations for users within their domain and with the identity:default role.

The functionality described in this section is provided by the RAX-AUTH extension.

Add a mobile phone

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Adds a mobile phone number to the specified user account to support multi-factor authentication.

The operation updates the specified user account with a phone number for multi-factor authentication. The same phone number can be associated with multiple accounts.

Add mobile phone: cURL request

$ curl $AUTH_URL/v2.0/users/$USER_ID/RAX-AUTH/multi-factor/mobile-phones  
       -X POST  
       -H "Content-Type: application/json"  
       -H "X-Auth-Token: $AUTH_TOKEN"  
       -d '{"RAX-AUTH:mobilePhone": { "number": "+1 210-312-4600" }}'| python -m json.tool\`

ℹ️
Note
This example assumes that the endpoint URL, user ID, and authentication token have been exported to these environment variables: AUTH_URL, USER_ID, and AUTH_TOKEN.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	The mobile phone has been added to the user account.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid. For example, you might get this error if the phone number format is incorrect.
401	Unauthorized	You are not authorized to complete this operation.
403	Forbidden	You do not have permission to access the requested resource. This error might be returned if the user ID is invalid or if it does not exist.
500	Service Fault	The service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name	Type	Description
RAX-AUTH:mobilePhone	Object	Provides the mobile phone information for the account.
RAX-AUTH:mobilePhone.number	String (Required)	The phone number for the mobile phone you want to add in E.123 format. +1 235-435-623 or +44 42 1123 4567 for example.

Example: Add a mobile phone HTTP request header: XML

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456  
Content-type: application/xml

Example: Add a mobile phone request: XML

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456  
Content-type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<RAX-AUTH:mobilePhone number="+1 210-312-4600"  
     xmlns="[http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0](<>)"  
     xmlns:OS-KSADM="[http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0](<>)"  
     xmlns:atom="[http://www.w3.org/2005/Atom](<>)" xmlns:identity="[http://docs.openstack.org/identity/api/v2.0"/>](<>)

Example: Add a mobile phone HTTP request header: JSON

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456  
Content-type: application/json

Example: Add mobile phone request: JSON

{  
    "RAX-AUTH:mobilePhone": {  
    "number": "+1 210-312-4600"  
    }  
}

Response

This table shows the body parameters for the response:

Name	Type	Description
id	String (Required)	The unique, system- generated ID assigned to the phone added to the account.
verified	Boolean (Optional)	A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.
number	String (Required)	The phone number added to the user account for use with multi-factor authentication services. E.123 format. +1 235-435-623 or +44 42 1123 4567 for example.

Example: Add a mobile phone response: XML

<?xml version="1.0" encoding="UTF-8"?>

<mobilePhone id="e0de732f1b1c4fec9d4f266326123456" verified="false" number="+1 210-312-4600"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Add a moble phone response: JSON

{  
    "RAX-AUTH:mobilePhone": {  
        "id": "e0de732f1b1c4fec9d4f266326123456",  
        "number": "+1 210-312-4600"  
    }  
}

Send verification code to phone

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{phoneId}/verificationcode

This operation sends an SMS message with a PIN code to a phone added to an account for multi-factor authentication.

After you update an account with a mobile phone number for multi-factor authentication, Rackspace must confirm that the user has the phone before it can be enabled for use in the authentication process.

When you send the verification code, include the phoneId in the API request. If you don’t know the ID, use the List multi-factor devices associated with operation to get it.

After you submit request, the Rackspace verification service sends a PIN to the specified phone via SMS text message. Each PIN has a system-defined expiration time determined by the Identity service system configuration. After receiving the PIN, use the Verify a mobile phone operation to submit the PIN to the Identity service to confirm the device for use with multi-factor authentication services.

⚠️
Important
In the Send Verify request, the X-Auth-Token header parameter value must specify a valid authentication token ID for the user account associated with the mobile phone. If you submit an authentication token from any other account, the operation fails.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Accepted	The request was accepted for processing.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{userId}	String (Required)	The unique, system- generated user ID for an account.
X-Auth-Token	String (Required)	A valid authentication token.
{phoneId}	String (Required)	The ID for the phone associated with the user account.

This operation does not accept a request body.

Example Send verification code: JSON request in a cURL command

$ curl $AUTH_URL/v2.0/users/$USER_ID/RAX-AUTH/multi-factor/mobile-phones/$PHONE_ID/verificationcode  
  -X POST  
  -H "Content-Type: application/json"  
  -H "Accept: application/json"  
  -H "X-Auth-Token: $AUTH_TOKEN"        | python -m json.tool

ℹ️
Note
This example assumes that the endpoint URL, user ID, and your authentication token have been exported to environment variables.

Response

This operation does not return a response body.

Verify a mobile phone

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{phoneId}/verify

Use this operation to submit the verification PIN from the SMS text message sent by Rackspace. After the PIN is accepted, use the Update settings for multi-factor authentication operation to enable multi-factor authentication on the user account.

When you send the verification code, include the phoneId in the API request. If you don’t know the ID, use the List phones for user operation to get it.

This operation can only be completed from the user account that the phone is associated with. The operation fails if the PIN is expired, or if it doesn’t match the code issued by the Rackspace verification service.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
415	Bad Media Type	Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.
{phoneId}	String (Required)	The unique, system- generated ID assigned when a phone is added to an account.

This table shows the body parameters for the request:

Name	Type	Description
RAX-AUTH:verificationCode	Object	Provides the value to verify a phone for multifactor authentication.
RAX-AUTH:verificationCode.code	String (Required)	The unique PIN code from the SMS text message sent by the Rackspace Cloud verification service.

Example: Verify device: XML request

<?xml version="1.0" encoding="UTF-8"?>

<verificationCode
     code="1234"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Verify device: JSON request

{  
    "RAX-AUTH:verificationCode": {  
        "code": "1234"  
    }  
}

Response

This operation does not return a response body.

List multi-factor mobile phone by device ID

GET v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{mobilePhoneId}

When you configure a user account with multi-factor authentication by mobile phone, the Identity system assigns a unique device ID to the phone. If you know the device ID, you can use this operation to look up the phone number associated with the specified ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.
{mobilePhoneId}	URI String (Required)	The unique, system- generated ID for a mobile phone that has been registered for use as a multi-factor authentication device.

This operation does not accept a request body.

Example: Retrieve multi-factor phone for a user HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Example: Retrieve multi-factor phone for user by device ID request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
RAX-AUTH:mobilePhones	Object (Required)	An array that returns phone ID and status information.
RAX-AUTH:mobilePhones.id	String (Required)	A unique, system- generated string that identifies the mobile phone in the Identity service.
RAX-AUTH:mobilePhones.number	String (Required)	Phone number of the device associated with the user account. Use the Add mobile phone operation to add a phone to the account. Use the remove multi-factor operation to delete phones from the account.
RAX-AUTH:mobilePhones.verified	Boolean (Optional)	A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.

Example: Lists multi-factor phones for user response: XML

<?xml version="1.0" encoding="UTF-8"?>

<mobilePhone id="12345" number="12658943489" verified="false"
  xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
  xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
  xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Lists multi-factor phones for user response: JSON

{  
 "RAX-AUTH:mobilePhone": {  
   "id": "12345",  
   "verified": false,  
   "number": "12658943489"  
  }  
}

List multi-factor phones for user

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Use this operation to get a list of the mobile phones associated with the specified user account.

A user or Identity administrator impersonating a user can use this operation to list the mobile phones associated with a user account.

You can retrieve a specific phone by including the unique, system-generated ID assigned to the phone when it was added to the Rackspace Cloud account.

An account can have up to one mobile phone configured for multi-factor authentication.

If you don’t know the user ID, use the List user operation to find it.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example List multi-factor phones for user: XML request

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Example List multi-factor phones for user request: JSON request

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
RAX-AUTH:mobilePhones	Object (Required)	An array that returns phone ID and status information.
id	String (Required)	A unique, system- generated string that identifies the mobile phone in the Identity service.
number	String (Required)	Phone number of the device associated with the user account. Use the Add mobile phone operation to add a phone to the account. Use the remove multi-factor operation to delete phones from the account.
verified	Boolean (Optional)	A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.

Example Lists multi-factor phones for user: XML response

<?xml version="1.0" encoding="UTF-8"?>

<mobilePhones
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0">  
     <mobilePhone id="12345" number="+1 265-894-3489" verified="true"/>  
</mobilePhones>

Example Lists multi-factor phones for user: JSON response

{  
  "RAX-AUTH:mobilePhones": [  
    {  
      "id": "12345",  
      "verified": true,  
      "number": "12658943489"  
    }  
  ]  
}

Remove phone from account

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Removes a phone number associated with a user account to support multi-factor authentication.

This operation removes the multi-factor authentication setting from your account along with all phones associated with the account. To disable the feature without removing phones, use the Disable multi-factor setting operation.

This operation allows users and administrators to remove a mobile phone number added to an account to support multi-factor authentication. You can remove the number if multi-factor authentication is disabled, or if the user has decided to use an OTP device for multi-factor authentication.

This operation can only be completed from the user account submitting the request. Attempts to run it for a different user ID result in a 403 error message.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Remove phone from account: XML request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/1234 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/xml

Example: Remove phone from account: JSON request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/1234 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Response

This operation does not return a response body.

Create an OTP device

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices

Adds an OTP (one-time password) device for multi-factor authentication.

You can add up to five OTP devices to a user account. After adding the device, use the verify OTP device.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	The OTP device has been added to the user account.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation.
500	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Add an OTP device HTTP request header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1  
Host: staging.identity-internal.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 83aa159390854e4690e4834e0cfa1234  
Content-type: application/xml

Example: Add an OTP device request: XML

<?xml version="1.0" encoding="UTF-8"?>

<otpDevice name="NewOTPDevice"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Add an OTP device HTTP request header: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1  
Host: staging.identity-internal.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0cfa1234  
Content-type: application/json

Example: Add an OTP device request: JSON

{  
    "RAX-AUTH:otpDevice": {
    "name": "NewOTPDevice"
    }
}

Response

This table shows the header parameters for the response:

Name	Type	Description
Location	AnyURI (Required)	URI for the newly created OTP device.

This table shows the body parameters for the response:

Name	Type	Description
id	String	The unique, system- generated ID assigned to the OTP device.
keyUri	String	The URI for the device security token.
name	String	The unique name assigned to the OTP device.
qrcode	String	The bar code to identity the OTP device to the mobile passcode application.
verified	Boolean	Indicates whether the OTP device has been verified.

Example: Add an OTP device HTTP response header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/json

Example: Add an OTP device response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rax-auth:otpDevice  
     xmlns:atom="[http://www.w3.org/2005/Atom](<>)"  
     xmlns:rax-auth="[http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0](<>)"  
     xmlns="[http://docs.openstack.org/identity/api/v2.0](<>)"  
     xmlns:ns4="[http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0](<>)"  
     xmlns:rax-ksqa="[http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0](<>)"  
     xmlns:os-ksadm="[http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0](<>)"  
     xmlns:rax-kskey="[http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0](<>)"  
     xmlns:os-ksec2="[http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">](<>)  
     <rax-auth:otpDevice  
          id="6b2834a8bef6461e96ef2322b4c72998"  
          keyUri="otpauth://totp/Example:alice@google.com?secretu003dJBSWY3DPEHPK3PXPu0026issueru003dExample"  
          qrcode="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAKAAQAAAAAktvSOAAADJklEQVR42u3dPXLqMBAAYGVekTJHyFFytHA0juIjpKRg0HP8I68E5Gcmtik+NyAwH51md7WSU/7jKwGBQCAQCAQCgUAgEAgEAoFAIBC4Bpji9T5+dkovw+shpacyPPbf9y/neP8TEAgE7gcuHx57MNz91oPTNx/TsL/5nJ5v/RYIBAJ3AMcp7nUEx+E8AU7XS7z5efDTeDMQCAQ+CDgEbJ8zXjdHd6PfDfdM3wKBQODjgf2bf0P62fXxW5kA85ScAoFA4EOBV9no/JNSPbvpZyAQCNwVrNcCSr4ZktNm+LvFBSAQCFwJbDsqYvXskK6nx9+2dgCBQOBKYEk/p16LyzAMtbXxCuHcnLpWPhAIBG4NhvrY0HrxCeYpfktxPnyb/z1/nY0CgUDgRuCl3HMcE8xY7S9tsd2Sq1apKxAIBO4FVo2veV4LyEvrxdwHW5Xa0hzdAYFA4G5g0/i6DEMxbcxGmyEQCATuCvbhXCz+D8Pnko3m3LaZpWmYgUAgcF9wWgsoe8AvZWkg5Kofy57K8+2VTSAQCNwcfLpuqziVPeBtJ0b8uwMQCAQ+CDh1YqTQ+Bo6Maq1gNdczucBAoHAfcAiNJ0Y5ZobM6ba2rLu+X6nsRYIBAI3AUvAVm07KtX+q+L/OZTa7q+NAoFA4Opg6bUI5f3TErClUExrams532vjBwKBwK3AUwnepuiuHCB2qQ7k+UkxDQgEAjcCl+pZk2/eng/j331dTAMCgcBVwWqx8r09X7q0mXVxU9J3jWRAIBC4ARimuLec6+Nbw2Jl1x4vlu9mo0AgELgJeGsXUrPP6FRvsVw6MYBAIHBHsJ3XUr0L6VKEsHYZ1j2BQCBwL/D69Okci/+5it+qcO6Q7jeSAYFA4Ppg/eyPcnxrKKZdnVkRHoMLBAKBO4LNgyNv9pVNs2V9hMVX6S0QCARuC4YTLUI4l2N0992zkIBAIHAPsBxGHfpgl02UIdj7cTgHBAKBq4ExGw27kI5VnW0RTt+Gc0AgELgFeLUWcC6Nr+HEsC6uFKTfLS4AgUDgGuAfXUAgEAgEAoFAIBAIBAKBQCAQCAQ+MvgfowFRJtozjAcAAAAASUVORK5CYIIu003d",  
          name="NewOTPDevice">  
</rax-auth:otpDevice>

Example: Add a moble phone HTTP response header: JSON

HTTP/1.1 200 OK  
Content-Length: 1985  
Content-Type: application/json  
LOCATION: <http://identity.api.rackspacecloud.com/cloud/v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/a34b5e4a1ffe4514a8859716136dc7cb>  
Date: Tue, 05 May 2015 14:09:02 GMT

Example: Add a moble phone response: JSON

{  
    "RAX-AUTH:otpDevice": {  
        "id": "58c4e0f6ca9745a9b97bcad9796685cd",  
        "keyUri": "otpauth://totp/Rackspace:AngelaTestMobile1?secret=IU4K3ZYVOKKCI4Z3UZTSKBXOCWMXVGLW&issuer=Rackspace",  
        "name": "NewOTPDevice",  
        "qrcode": "data:image/png;base64,tVBORw0KGgoAAAANSUhEUgAAAoAAAAKAAQAAAAAktvSOAAADQUlEQVR42u3dS3KrMBCF4WbEMlgqLJVlMELXwRI6rQeRkztK/UxSEPw5I5X6oY6F/3wZICAgICAgICAgICAgICAgICDgHwcPy9f0ulvej3dbz9eT191p89fd++F1LWGTDy2AgICAY2B6ErYInteLa8h3+VvuN6uPAwICAn4LbnFRmq7FLErpLi5fZ1q35vTVfr0DBAQE/BS0Ke2g5rQ9it8SHwICAgL+GrzCrynHazE0CykY80sbICAg4GeghmbXazEKKxesRX4Mx3qAgICAnbTzNvDjozw2ICAgYPNqJHtMEkGZGK3RAwICAsblK+2LJlfruotcc65upevMSaIFEBAQcASU1M/6zvloA08OzUxrXekPkQ8AAgICPoNHEZPlRND9drlZ0lguAAICAo6BdZ+g+Ttz+6IzhW2+axAQEBDwe1D3RZa3QDEflAlpHsw7qHZoBggICNisSfnUjy5mvke56uOxZqwHCAgI2EkE6e/3dj1rK/NB8zuBFAABAQHHQC2bxyS05fDr/uxaltsDICAg4EdgrJD7LPLN6wqnVTFLy9fRbhcEBAQEbB6F0NJ4uW65tFB1/qq1HgICAgI+gbucuGrukqTktdYrHCAgIOAgGMqSuiSJzM3l2osgDhAQEHAI9NNw9IDD4Vp25Fv8gVBAQEDAATDICK6zcb6zMazrPgphvZI6ICAgYLuBR4YB5lr6WT201Fi4nvXZckBAQMARUNM7MtP4zg6Zn13hjoACAgICDoDlvkibk+ecK9KHz0chAAEBAbfe/5NqvJ2TPdYiHpcvQEBAwM5mKfiuZJcWCqEasl4N6wIEBAQcBKWkvhRdg7llx6eMQlH5AgQEBHwGtYLVeE2yz6FYzJ4SQYCAgIDdzVLotOz4oxAy7KLTnAwICAjYOblQThLV6nk1PsfMiiGlgICAgIOgBmNHMV60cX68McgLEBAQcAz07YL+Q6Gc+ydJaEBAQMCfgnXzoMmEQG31eZj3BQgICDgA7i1CQ7O5PE0OCAgIOAr60MxP4jJzU7p0wWqPVQcEBATcHkrq5o5CBNfOc7iWHflvndY9WwEICAi4PJbUf3EBAgICAgICAgICAgICAgICAgL+VfAf+kH5tccf0ykAAAAASUVORK5CYII=",  
        "verified": false  
    }  
}

Verify an OTP device

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}/verify

Sends the mobile passcode from the mobile passcode application to the Identity service to pair the OTP device instance with the account.

After you set up an OTP device for multi-factor authentication this operation sends the passcode from the mobile passcode application to the Identity service to confirm that you have the device so that you can use the device for multi-factor authentication.

If your account is set up for multi-factor authentication by using a mobile phone, or if this is the first OTP device on your account, update the multi-factor authentication settings on your account to use the OTP device.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	String (Required)	The unique, system- generated user ID for an account.
{otpDeviceId}	String (Required)	The unique system- generated ID assigned to the OTP device.

This table shows the body parameters for the request:

Name	Type	Description
verified	Boolean (Required)	Indicates whether the OTP device has been verified.

Example: : Verify OTP devices for account HTTP request header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/  
12345e4a1ffe4514a8859716136dc7cb/verify HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0c123456  
Content-type: application/json

Example: : Verify OTP devices for account request: XML

<?xml version="1.0" encoding="UTF-8"?>

<verificationCode code="123456"
    xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
    xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: :Verify OTP devices for account HTTP request header: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/  
a34b5e4a1ffe4514a8859716136dc7cb/verify HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/json

Example: :Verify OTP devices for account request: JSON

{“RAX-AUTH:verificationCode”: { “code”: “662262” }}

Response

Example: : Verify device by ID HTTP response

HTTP/1.1 204 No Content

List the specified OTP device

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}

This operation returns the OTP device associated with the account.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.
{otpDeviceId}	String (Required)	The unique system- generated ID assigned to the OTP device.

This table shows the body parameters for the request:

Name	Type	Description
otpDevice	Object	Returns the following information for an OTP device: ID, name, verification status.
otpDevice.id	String	The unique system- generated ID assigned to the OTP device.
otpDevice.name	String	The unique name assigned to the OTP device.
otpDevice.verified	Boolean	Indicates whether the OTP device has been verified.

Example:: Get OTP devices for account HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/xml

Example:: Get OTP devices for account HTTP request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/json

Response

Example: Get OTP devices for account HTTP response header: XML

HTTP/1.1 200 OK  
Content-Type: application/xml

Example: Retrieves the specified OTP device response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rax-auth:otpDevices  
     xmlns:atom="[http://www.w3.org/2005/Atom](<>)"  
     xmlns:rax-auth="[http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0](<>)"  
     xmlns="[http://docs.openstack.org/identity/api/v2.0](<>)"  
     xmlns:ns4="[http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0](<>)"  
     xmlns:rax-ksqa="[http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0](<>)"  
     xmlns:os-ksadm="[http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0](<>)"  
     xmlns:rax-kskey="[http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0](<>)"  
     xmlns:os-ksec2="[http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">](<>)  
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>  
</rax-auth:otpDevices>

Example: Get OTP devices for account HTTP response header: JSON

HTTP/1.1 200 OK  
Content-Type: application/json

Example: Retrieves the specified OTP device response: JSON

{  
    "RAX-AUTH:otpDevice": {  
        "id": "6b2834a8bef6461e96ef2322b4c72998",  
        "verified": true,  
        "name": "NewOTPDevice"  
    }  
}

Get the OTP devices for a specified account

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices

This operation returns information about the OTP devices associated with a user account.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Get OTP devices for account HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 9c069077e4eb438daf8527ba7cc0a7ad  
Content-type: application/xml

Example: Get OTP devices for account HTTP request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9c069077e4eb438daf8527ba7cc0a7ad  
Content-type: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
otpDevices	Object	Returns the collection of OTP devices associated with the specified account.
otpDevices.otpDevice	Object	Returns information about each OTP device associated with the specified account.
otpDevice.id	String	The unique system- generated ID assigned to the OTP device.
otpDevice.name	String	The unique name assigned to the OTP device.
otpDevice.verified	Boolean	Indicates whether the OTP device has been verified.

Example: Gets the OTP devices for a specified account HTTP response header: XML

HTTP/1.1 200 OK  
Content-Type: application/xml

Example: Gets the OTP devices for a specified account response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rax-auth:otpDevices  
     xmlns:atom="[http://www.w3.org/2005/Atom](<>)"  
     xmlns:rax-auth="[http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0](<>)"  
     xmlns="[http://docs.openstack.org/identity/api/v2.0](<>)"  
     xmlns:ns4="[http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0](<>)"  
     xmlns:rax-ksqa="[http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0](<>)"  
     xmlns:os-ksadm="[http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0](<>)"  
     xmlns:rax-kskey="[http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0](<>)"  
     xmlns:os-ksec2="[http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">](<>)  
     <rax-auth:otpDevice verified="false" name="NewOTPDevice1" id="22eec7c1f65a4615945d89e38786a6b3"/>  
     <rax-auth:otpDevice verified="false" name="NewOTPDevice" id="a34b5e4a1ffe4514a8859716136dc7cb"/>  
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>  
</rax-auth:otpDevices>

Example: Gets the OTP devices for a specified account HTTP response: JSON

HTTP/1.1 200 OK  
Content-Type: application/xml

Example: Gets the OTP devices for a specified account: JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rax-auth:otpDevices  
     xmlns:atom="[http://www.w3.org/2005/Atom](<>)"  
     xmlns:rax-auth="[http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0](<>)"  
     xmlns="[http://docs.openstack.org/identity/api/v2.0](<>)"  
     xmlns:ns4="[http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0](<>)"  
     xmlns:rax-ksqa="[http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0](<>)"  
     xmlns:os-ksadm="[http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0](<>)"  
     xmlns:rax-kskey="[http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0](<>)"  
     xmlns:os-ksec2="[http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">](<>)  
     <rax-auth:otpDevice verified="false" name="NewOTPDevice1" id="22eec7c1f65a4615945d89e38786a6b3"/>  
     <rax-auth:otpDevice verified="false" name="NewOTPDevice" id="a34b5e4a1ffe4514a8859716136dc7cb"/>  
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>  
</rax-auth:otpDevices>

Example: Get the OTP devices for a specified account HTTP response header: JSON

HTTP/1.1 200 OK
Content-Type: application/json

Example: Get the OTP devices for a specified account response: JSON

{  
    "RAX-AUTH:otpDevices": [  
        {  
            "id": "22eec7c1f65a4615945d89e38786a6b3",  
            "verified": false,  
            "name": "NewOTPDevice1"  
        },  
        {  
            "id": "a34b5e4a1ffe4514a8859716136dc7cb",  
            "verified": false,  
            "name": "NewOTPDevice2"  
        },  
        {  
            "id": "6b2834a8bef6461e96ef2322b4c72998",  
            "verified": true,  
            "name": "NewOTPDevice"  
        }  
    ]  
}

Remove a specified OTP device from a user account

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}

This operation deletes the OTP device with the specified ID from the user account.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.
{otpDeviceId}	String (Required)	The unique system- generated ID assigned to the OTP device.

This operation does not accept a request body.

Example: Delete OTP device by ID: XML request header

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/xml

Example: Delete OTP device by ID: JSON request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c  
Content-type: application/json

Response

Example: Delete device by ID HTTP response

HTTP/1.1 204 No Content

This operation does not require a request body and does not return a response body.

Update multi-factor authentication settings on account

PUT /v2.0/users/{userId}/RAX-AUTH/multi-factor

Use this operation to update the multi-factor authentication settings for the specified account.

You can only use this operation on accounts that have been set up for multi-factor authentication.

You can use the userMultiFactorEnforcementLevel parameter to override the multi-factor domain enforcement setting on an account. Note that this feature is available only through the API. You cannot override domain enforcement settings from the Rackspace Cloud Control Panel.

ℹ️
Note

Customers need a support ticket if they want to update a user’s MFA enforcement setting when the domain MFA enforcement setting is RACKSPACE_MANDATED.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	Possible reasons: No multi-factor device on user account; multi factor phone on account is not verified.
403	Forbidden	Possible reasons: No multi-factor device on user account; multi factor phone on account is not verified.
403	Forbidden	Cannot update user enforcement level when domain enforcement level set as `RACKSPACE_MANDATED`.
500	Service Fault	Problem linking phone with Identity service multi-factor authentication service. Contact the Identity service administrator for help.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name	Type	Description
RAX- AUTH:multiFactor	Object (Optional)	A collection of multi-factor authentication settings.
RAX-AUTH:multiFactor.enabled	Boolean (Optional)	If an account has been configured for multi-factor authentication, this parameter specifies whether the feature is active on the account. account. Specify `enabled=true` to turn on multi-factor authentication. Specify `enabled=false` to turn it on. As soon as you enable multi-factor authentication on an account, any existing authentication tokens are are invalidated, and the account user must use multi-factor authentication process to regain access to their account.
RAX-AUTH:multiFactor.unlock	Boolean (Optional)	A Boolean value that indicates the lock status on a user account that is enabled for multi-factor authentication. To unlock an account, specify `unlock=true` in the Unlock operation request. .This attribute cannot be used to lock an account. If you submit the request with `unlock=false`, the operation does not make any changes to the account.
RAX-AUTH:multiFactor.userMultiFactorEnforcementLevel	String (Optional)	Specifies the user enforcement level for multi-factor authentication. `REQUIRED` The user must use multi- factor authentication to log in to their Rackspace Cloud account even if the domain enforcement level is configured as optional. `OPTIONAL.` The user has the option has the option to authenticate using multi-factor authentication even if the the domain enforcement level is configured as required. `DEFAULT.` The user multi-factor authentication requirements are determined by the domain-level authentication.

Example: Enable account for multi-factor authentication HTTP request header: XML

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/xml

Example: Enable account for multi-factor authentication: XML request

<?xml version="1.0" encoding="UTF-8"?>
<multiFactor
     enabled="true"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Enable account for multi-factor authentication HTTP request header: JSON

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/xml

Example: Enable multi-factor authentication on account request: JSON

{  
    "RAX-AUTH:multiFactor": {  
        "enabled": true  
    }  
}

Example: Disable multi-factor authentication on account HTTP request header: XML

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/xml

Example: Disable multi-factor authentication on account request: XML

<?xml version="1.0" encoding="UTF-8"?>
<multiFactor
     enabled="false"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Disable multi-factor authentication on account HTTP request header: JSON

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/xml

Example: Disable multi-factor authentication on account request: JSON

{  
    "RAX-AUTH:multiFactor": {  
        "enabled": false  
    }  
}

Example: Unlock account request: XML

<?xml version="1.0" encoding="UTF-8"?>

<multiFactor
     unlock="true"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Unlock account request: JSON

{  
    "RAX-AUTH:multiFactor": {  
        "unlock": true  
    }  
}

This operation does not accept a response body.

Example: Update user level enforcement for multi-factor authentication request: XML

<multiFactor
    userMultiFactorEnforcementLevel="OPTIONAL"
    xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
    xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>  
</multiFactor>

Example: Update user level enforcement request: JSON

{  
    "RAX-AUTH:multiFactor": {  
        "userMultiFactorEnforcementLevel": "OPTIONAL",  
    }  
}

Response

This operation does not return a response body.

Generate bypass codes

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/bypass-codes

Use this operation to generate bypass codes that can be substituted for a multi-factor authentication passcode. You can use these codes to recover access to an account if you are unable to retrieve the multi-factor authentication passcode from your multi-factor authentication device. In the request, you can specify the number of bypass codes to generate and set an expiration date for the generated codes.

Administrator-generated codes are valid for 30 minutes by default. Administrators can configure the validity duration from 1 to 180 minutes.

Each bypass code can be used only one time. A bypass code remains valid until it expires. Bypass codes are also invalidated if multi-factor authentication is disabled on the account associated with the bypass code.

ℹ️
Note

You can also generate bypass codes from the Account settings page in the Rackspace Cloud Control panel.

Users can always use this service to generate bypass codes for themselves.

Users with the identity:user-admin role can generate a single bypass code for any user within their domain.

Users with the identity:user-manage or identity:user-manage-limited role can generate a single bypass code for any sub user within their domain.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
415	Bad Media Type	Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name	Type	Description
RAX-AUTH:bypassCodes	Object String (Optional)	This object specifies the `validityDuration` and `numberofcodes` attributes for the Generate bypass codes operation. See the XML and JSON request examples for the correct syntax.
RAX-AUTH:bypassCodes.validityDuration	Duration (Optional)	Specifies the time interval that the bypass codes remain valid. If no value is specified, the value defaults to 30 minutes`PT30M`. If the bypass codes are for your own account, customize the value as needed. * Administrators can configure an interval between 1 and 180 minutes when creating a bypass code for another user account. The value is expressed in xsd:duration format, `PT20MPnYnMnDTnHnMnS`. `P` indicates the period (required) `nY` indicates the number of years `nM` indicates the number of months `nD` indicates the number of days `T` indicates the start time of a section. (required if the duration value includes hours, minutes, or seconds) `nH` indicates the number of hours `nM` indicates the number of minutes `nS` indicates the number of seconds
RAX-AUTH:bypassCodes.numberofcodes	Integer (Optional)	Specifies the number of bypass codes to generate codes to generate. If If not specified, the value defaults to `1`. Users can generate up to 10 bypass codes for their own account. Administrators can generate only one bypass code for user accounts other than their own.

Example: Generate bypass codes HTTP header request: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/bypass-codes HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/xml

Example:Generate bypass codes request: XML

<?xml version="1.0" encoding="UTF-8"?>

<bypassCodes validityDuration="PT20M" numberOfCodes="1"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Generate bypass codes HTTP header request: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/bypass-codes HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234  
Content-type: application/json

Example:Generate bypass codes request: JSON

{  
  "RAX-AUTH:bypassCodes": {  
    "validityDuration": "PT20M",  
    "numberOfCodes": "1"  
  }  
}

Response

This table shows the body parameters for the response:

Name	Type	Description
RAX-AUTH:bypassCodes	Object String (Optional)	This object returns the list of `bypass codes` and the `validityDuration` setting that specifies how long the codes are valid. See the XML and JSON request examples for the correct syntax.
RAX-AUTH:bypassCodes.codes	String list (Optional)	Returns a list of the generated bypass codes.
RAX-AUTH:bypassCodes.validityDuration	Duration (Optional)	The time interval that specifies how long the generated codes remain valid.

Example: Generate bypass codes HTTP response header: XML

HTTP/1.1 200 OK  
Content-Type: application/xml

Example:Generate bypass codes response: XML

<?xml version="1.0" encoding="UTF-8"?>

<bypassCodes validityDuration="PT10M0.000S" codes="123456789"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Generate bypass codes HTTP response header: JSON

HTTP/1.1 200 OK  
Content-Type: application/json

Example: Generate bypass codes response: JSON

{  
  "RAX-AUTH:bypassCodes": {  
    "codes": [  
      "123456789"  
    ],  
    "validityDuration":"PT20M0.000S"  
  }  
}

Update domain enforcement setting

PUT /v2.0/RAX-AUTH/domains/{domainId}/multi-factor

Updates the domain-level enforcement level for multi-factor authentication.

Identity administrators can set account-wide requirements for multi-factor authentication by setting the domain enforcement level. This setting applies to all user accounts within the domain specified in the update request. Before you set the domain enforcement level, the administrator account must be configured with multi-factor authentication.

ℹ️
Note

Administrators can override the domain-level enforcement level for specific user accounts by using the Update multi-factor authentication settings operation to set user level enforcement.

Customers need a support ticket if they want to update a domain to have the RACKSPACE_MANDATED mfa enforcement policy and also to update a domain’s mfa enforcement when it is already set to RACKSPACE_MANDATED.

Update domain enforcement settings:json cURL request

$ curl -X -i PUT identity.api.rackspacecloud.com/v2.0/RAX-AUTH/domains/$DOMAIN_ID/multi-factor  
  -d '{"RAX-AUTH:multiFactorDomain": {"domainMultiFactorEnforcementLevel": "OPTIONAL"}}\`  
  -H "Content-type: application/json"  
  -H "X-Auth-Token: $ADMIN_AUTH_TOKEN" --verbose | python -m json tool

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
400	Bad Request	Trying to set up domain- level enforcement setting on an account that has not been configured with multi- factor authentication. Set up multi-factor authentication on account.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
403	Forbidden	You must set up multi- factor authentication on your account before you can set multi-factor domain-level enforcement.
404	Not Found	The requested resource was not found.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the body parameters for the request:

Name	Type	Description
RAX- AUTH:multiFactorDomain	Object (Optional)	Specifies the domain enforcement level, `domainMultiFactorEnforcementLevel` for multi-factor authentication. Specify either of these values. `domainMultiFactorEnforcementLevel: "REQUIRED"` makes multi-factor authentication mandatory for all account users. `domainMultiFactorEnforcementLevel: "OPTIONAL"` Users within the domain can choose whether to use multi-factor authentication on their own accounts. `domainMultiFactorEnforcementLevel: "RACKSPACE_MANDATED"` makes multi-factor authentication mandatory for all account users. *
RAX-AUTH:multiFactorDomain.domainMultiFactorEnforcementLevel	String	The domain enforcement level for multi-factor authentication. Specify one of the following values: `REQUIRED` Authentication is mandatory for all account users within the specified domain. `OPTIONAL` Users within the specified domain can choose whether to use multi-factor authentication on their account. * `RACKSPACE_MANDATED` Authentication is mandatory for all account users within the specified domain.

Example: : Update domain settings for multi-factor authentication request: XML

<?xml version="1.0" encoding="UTF-8"?>

<multiFactorDomain domainMultiFactorEnforcementLevel="REQUIRED"
  xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
  xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
  xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: : Update domain settings for multi-factor authentication request: JSON

{
"RAX-AUTH:multiFactorDomain": {
    "domainMultiFactorEnforcementLevel": "REQUIRED"
    }
}

Response

This operation does not return a response body.

Remove mutlifactor authentication from account

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor

Removes the multi-factor authentication setting and all associated mobile phones from your user account.

This operation removes the multi-factor authentication setting from your account along with all phones associated with the account. To disable the feature without removing phones, use the update multi-factor settings on account operation to disable multi-factor authentication on the account.

ℹ️
Note

Users can always use this service to remove multi-factor authentication from themselves.

Users with the identity:user-admin role can remove multi-factor authentication from any user within their domain.

Users with the identity:user-manage or identity:user-manage-limited role can remove multi-factor authentication from any sub user within their domain.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No content	The request succeeded. The server fulfilled the request but does not need to return a body.
400	Bad Request	The request is missing one or more elements, or the values of some elements are invalid.
401	Unauthorized	You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.
403	Forbidden	The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.
405	Invalid Method	The method specified in the request is not valid for the resource identified in the request URI.
413	Over Limit	The number of items returned is above the allowed limit.
503	Service Fault	Service is not available.

Request

This table shows the header and URI parameters for the request:

Name	Type	Description
X-Auth-Token	Header String (Required)	A valid admin authentication token.
{userId}	URI String (Required)	The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Remove multi-factor authentication HTTP request header: XML

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/xml  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/xml

Example Remove multi-factor authentication HTTP request header JSON

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1  
Host: identity.api.rackspacecloud.com  
Accept: application/json  
X-Auth-Token: ab502872c7cc415483c945bcfc77322c  
Content-type: application/json

Response

This operation does not return a response body.