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:

Request

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

This table shows the body parameters for the request:

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:

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:

Request

This table shows the URI parameters for the request:

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:

Request

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

This table shows the body parameters for the request:

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:

Request

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

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:

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:

Request

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

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:

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:

Request

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

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:

Request

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

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:

This table shows the body parameters for the response:

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:[email protected]?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:

Request

This table shows the header URI parameters for the request:

This table shows the body parameters for the request:

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:

Request

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

This table shows the body parameters for the request:

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:

Request

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

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:

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:

Request

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

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:

Request

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

This table shows the body parameters for the request:

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:

Request

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

This table shows the body parameters for the request:

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:

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:

Request

This table shows the body parameters for the request:

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:

Request

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

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.