Auth0 My Account API: Let Users Manage Their Own Account

Why This Matters Now

In the world of modern web applications, enabling users to manage their own account details seamlessly is crucial. Traditionally, this required developers to use the Auth0 Management API, which comes with significant administrative power and necessitates server-side handling. This setup often led to added complexity and development overhead, especially for Single Page Applications (SPAs) and mobile apps. The introduction of the Auth0 My Account API addresses these challenges by providing a secure, client-side solution for user self-service management.

Introducing the My Account API

The My Account API is a specialized set of endpoints designed for client-side self-service. Unlike the Management API, which requires high-privilege tokens and server-side handling, the My Account API operates within the context of the currently logged-in user. This means all API calls are scoped to the /me path, ensuring they are limited to the authenticated user’s profile.

Key Design Choices

1. Client-Side Operation: The API is intended to be used directly from the client side, such as in a browser-based React application or a mobile app. This eliminates the need for a dedicated backend proxy, simplifying your architecture.
2. Scoped Access: By scoping API calls to the /me path, the API ensures that operations are limited to the authenticated user’s profile, enhancing security.
3. Standard Tokens: The API uses access tokens issued during the standard user login process, eliminating the need for high-privilege tokens.

Why It Matters

By leveraging the My Account API, developers can enable users to perform actions like updating profile information, enrolling in Multi-Factor Authentication (MFA), and linking social accounts directly from the client side. This not only improves the user experience but also reduces the complexity and overhead associated with traditional server-side implementations.

Activating the My Account API

To start using the My Account API, you need to activate it for your Auth0 tenant. Follow these steps:

1. Navigate to the Dashboard: Log in to your Auth0 dashboard and go to Authentication > APIs.
2. Activate the API: Look for the banner indicating the availability of the My Account API and click the Activate button.
3. Configure Audience and Scopes: Once activated, you’ll find the API identifier (audience) in the Settings tab. Note this value as you’ll need it for API requests.

Configuring Scopes

Scopes define the permissions granted to the API. It’s crucial to enable only the scopes your application needs. Here’s how:

1. Go to Applications: Navigate to the Applications tab in the My Account API settings.
2. Enable the API: Toggle the switch to enable the API for your application.
3. Select Scopes: Expand the scope section and select the necessary scopes. For example, use read:me:authentication-methods to allow users to view their enrolled authentication methods.
4. Save Changes: Click Update to save your configuration.

Getting Access Tokens

To interact with the My Account API, you need to obtain an access token with the appropriate audience and scopes. This token is typically acquired during the user login process. Here’s an example of an authorization request:

curl --request GET \
--url 'https://YOUR_AUTH0_DOMAIN/authorize' \
-d 'client_id=1234567890' \
-d 'response_type=code' \
-d 'redirect_uri=https://my-app.com/callback' \
-d 'audience=https://YOUR_AUTH0_DOMAIN/me/' \
-d 'scope=read:me:authentication-methods read:me:connected_accounts' \
-d 'state=wo87trfgwcdf2' \
-d 'nonce=dh9812hdd29' \
-d 'code_challenge=p2g8guffhp9hf398yyhh328' \
-d 'code_challenge_method=S256'

Using Auth0 SDKs

For JavaScript-based applications, consider using the myaccount-js SDK. This SDK simplifies the process of obtaining and managing access tokens. Here’s a basic example:

import { MyAccount } from '@auth0/myaccount-js';

const myAccount = new MyAccount({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientId: 'YOUR_CLIENT_ID',
  audience: 'https://YOUR_AUTH0_DOMAIN/me/',
  scope: 'read:me:authentication-methods read:me:connected_accounts'
});

// Get access token
myAccount.getAccessToken().then(token => {
  console.log('Access Token:', token);
});

Calling the API Directly

Understanding the raw HTTP requests involved in interacting with the My Account API is essential. Here’s an example of how to read the user’s currently enrolled authentication methods:

curl --request GET \
--url 'https://YOUR_AUTH0_DOMAIN/me/authentication-methods' \
--header 'Authorization: Bearer USER_ACCESS_TOKEN' \
--header 'Content-Type: application/json'

Common Scopes

Here are some common scopes you might need:

• read:me:authentication-methods: Allows reading the user’s enrolled authentication methods.
• create:me:authentication-methods: Allows creating new authentication methods.
• read:me:connected_accounts: Allows reading linked social accounts.
• delete:me:connected_accounts: Allows deleting linked social accounts.

Error Handling

When calling the API, be prepared to handle potential errors gracefully. Here’s an example of a common error response:

{
  "error": "invalid_scope",
  "error_description": "The provided scope is invalid or not allowed."
}

Simplifying API Calls with the SDK

The myaccount-js SDK provides a convenient way to interact with the My Account API. Here’s how to use it to read the user’s authentication methods:

myAccount.get('/authentication-methods').then(response => {
  console.log('Authentication Methods:', response.data);
}).catch(error => {
  console.error('Error:', error);
});

Updating Profile Information

To update a user’s profile information, you can use the patch method:

myAccount.patch('/profile', {
  name: 'John Doe',
  email: '[email protected]'
}).then(response => {
  console.log('Profile Updated:', response.data);
}).catch(error => {
  console.error('Error:', error);
});

Enrolling in MFA

Enrolling a user in MFA involves creating a new authentication method:

myAccount.post('/authentication-methods', {
  type: 'otp',
  options: {
    issuer: 'Your App',
    accountName: '[email protected]'
  }
}).then(response => {
  console.log('MFA Enrolled:', response.data);
}).catch(error => {
  console.error('Error:', error);
});

Best Practices

1. Scope Limitation: Always enable only the necessary scopes to minimize security risks.
2. Token Management: Securely manage access tokens to prevent unauthorized access.
3. Error Handling: Implement robust error handling to manage API errors effectively.
4. Testing: Thoroughly test your implementation to ensure it meets your requirements.

Conclusion

The Auth0 My Account API revolutionizes user self-service management by enabling client-side operations without compromising security. By activating the API, configuring the necessary scopes, and using the provided SDKs, developers can streamline user account management in their applications. This not only enhances the user experience but also simplifies the development process, making it easier to implement essential features like profile updates and MFA enrollment.

That’s it. Simple, secure, works. Start implementing the My Account API today to take advantage of these benefits.