Setting up Multi-Factor Auth (MFA)¶
PolyAPI supports multi-factor authentication (MFA) for added security.
Enable MFA for your Instance¶
To turn on MFA, if you are a self-hosting customer managing your own instance, please have a super admin set the following instance-wide config variable:
PATCH /config-variables/MfaEnabled
{"value": true}
Replace https://na1.polyapi.io with your instance’s URL.
In the near future, tenant-level MFA will also be possible. Please contact support@polyapi.io to set this up.
Setup MFA for your Account¶
To setup MFA for your account, please hit the following endpoint:
POST /otp/setup
You should receive back a QR code. Please scan the QR code with your Authenticator app of choice!
(Note: if you are on desktop, you can also receive your secret key as plaintext via the /otp/pair endpoint, which you can then manually type into your desktop Authenticator app.)
Verify MFA for your Account¶
Before you can use MFA, you must verify it. To do so, please hit the following endpoint:
POST /otp/verify
{"token": "123456"}
If you have provided a valid token, you should receive back a 200 response.
Great! You are setup and ready to go with MFA! Now let’s use it.
Use MFA for your Account¶
To use MFA on an endpoint that requires it, please add your OTP via the following header:
x-otp: 123456
For example, on the create users endpoint for tenant 123, the request would look like this:
Note
Right now, MFA is only supported by the API.
In the August or September 2024 releases, MFA support will also be added to the UI!
Victory¶
That’s it!
You are now setup with MFA, providing additional security to your PolyAPI account.
Reset MFA¶
If at any point, you want to reset your MFA please hit the following endpoint:
POST /tenants/123/users/456/reset-mfa
This will reset MFA for user 456 in tenant 123.
The common use case for this is if a user gets a new MFA device, like a new phone.
User 456 can then to go back to the Setup flow and go through MFA setup again on a new device.
Note
If you are a super admin managing your own instance and want to reset MFA, please contact support@polyapi.io for assistance.
Additional verification is required for super admin users.