Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
Manage Users

Manage User Tokens

On this page

  • Get a User Access Token
  • Manually Refresh an Access Token
  • Configure Refresh Token Expiration

The SDK manages two types of user tokens:

  • User access token: a token sent with each request to Atlas. Without a valid access token, the app can't perform server-related functionality on the user's behalf.

  • Refresh token: a token used to refresh the access token. The SDK uses this to automatically rotate the access token, up to the period when the refresh token expires.

Once the refresh token expires, the app can't perform operations that involve the server until the user logs in again.

Tokens are removed after the user logs out.

Important

The SDK Automatically Handles User Access Tokens for Most Functionality

The SDK automatically handles user access tokens for operations that it performs, such as calling a Function or syncing the device database. It sends the access token with each request, and automatically handles refreshing it. When a refresh token expires, your app code must redirect users to login again.

If you send requests outside of the SDK, you must include the user's access token with each request and manually refresh the token when it expires. You must manually manage this token when calling Atlas Data API endpoints from your client code, for example.

For more information on user session access and refresh tokens, refer to User Sessions in the App Services documentation.

Get a User Access Token

Access tokens expire 30 minutes after a user logs in.

You can call .refresh_custom_user_data() on a logged-in user to refresh the user's auth session. Then, get the .access_token() as a string you can use in your code. You might use code similar to this to fetch an access token:

You can get the current access token for a logged-in user with the user.accessToken property:

You can call .refreshCustomData() on a logged-in user to refresh the user's auth session. Then, return the .accessToken as a string you can use in your code. You might use a function similar to this to fetch an access token:

// With a logged-in user, refresh the custom user data to refresh the auth
// session
user.refresh_custom_user_data().get();
// Then get the user's access token
auto userAccessToken = user.access_token();
// Returns a valid user access token to authenticate requests
public async Task<string> GetValidAccessToken(User user)
{
    // An already logged in user's access token might be stale. To
    // guarantee that the token is valid, refresh it.
    await user.RefreshCustomDataAsync();
    return user.AccessToken;
}
final token = app.currentUser?.accessToken;
// Gets a valid user access token to authenticate requests
public String getValidAccessToken(User user) {
    // An already logged in user's access token might be stale. To
    // guarantee that the token is valid, refresh it if necessary.
    user.refreshCustomData();
    return user.getAccessToken();
}
// Gets a valid user access token to authenticate requests
async function getValidAccessToken(user) {
  // An already logged in user's access token might be stale. To
  // guarantee that the token is valid, refresh it if necessary.
  await user.refreshCustomData();
  return user.accessToken;
}
val token = user.accessToken
// Gets a valid user access token to authenticate requests
fun getValidAccessToken(user: User?): String {
    // An already logged in user's access token might be stale. To
    // guarantee that the token is valid, refresh it if necessary.
    user!!.refreshCustomData()
    return user.accessToken
}
func getValidAccessToken(user: User) async throws -> String {
    // An already logged in user's access token might be stale. To
    // guarantee that the token is valid, refresh it if necessary.
    try await user.refreshCustomData()
    return user.accessToken!
}
// Gets a valid user access token to authenticate requests
async function getValidAccessToken(user: Realm.User) {
  // An already logged in user's access token might be stale. To
  // guarantee that the token is valid, refresh it if necessary.
  await user.refreshCustomData();
  return user.accessToken;
}

Manually Refresh an Access Token

You can manually refresh an expired access token.

You can call .refresh_custom_user_data() on a logged-in user to refresh the user's auth session.

Refresh an access token with User.refreshCustomData().

Future<String> getValidAccessToken(User user) async {
  // An already logged in user's access token might be stale. To
  // guarantee that the token is valid, refresh it if necessary.
  await user.refreshCustomData();
  return user.accessToken;
}

You can also periodically refresh the access token with Timer.periodic() from the dart:async library. Wrap the call to User.refreshCustomData() with the timer's callback function.

You can get the current refresh token for a logged-in user with the user.refreshToken property, which you can use to request a new access token:

You can call .refreshCustomData() on a logged-in user to refresh the user's auth session. Then, return the .accessToken as a string you can use in your code. You might use a function similar to this to fetch an access token:

// With a logged-in user, refresh the custom user data to refresh the auth
// session
user.refresh_custom_user_data().get();
// Then get the user's access token
auto userAccessToken = user.access_token();
// The documentation does not currently have this code example in C#.
// Please refer to the other languages or related pages for example code.
// Refresh the token every 29 minutes
Timer.periodic(Duration(minutes: 29), (_) {
  app.currentUser?.refreshCustomData();
});
// The documentation does not have this code example in Java.
// Please refer to the other languages or related pages for example code.
// The documentation does not currently have this code example in JavaScript.
// Please refer to the other languages or related pages for example code.
// Gets the current refresh token for the user
fun getRefreshToken(): String {
    return user.refreshToken
}
// The documentation does not have this code example in Kotlin for the Java SDK.
// Please refer to the other languages or related pages for example code.
func getValidAccessToken(user: User) async throws -> String {
    // An already logged in user's access token might be stale. To
    // guarantee that the token is valid, refresh it if necessary.
    try await user.refreshCustomData()
    return user.accessToken!
}
// The documentation does not currently have this code example in TypeScript.
// Please refer to the other languages or related pages for example code.

Configure Refresh Token Expiration

Refresh tokens expire after a set period of time. When the refresh token expires, the access token can no longer be refreshed and the user must log in again.

If the refresh token expires after the database is open, the device cannot sync until the user logs in again. Your sync error handler should implement logic that catches a token expired error when attempting to sync, then redirect users to a login flow.

For information on configuring refresh token expiration, refer to Configure Refresh Token Expiration in the App Services documentation.

Back

Authenticate Users

Next

Custom User Data

On this page