Docs Menu

Docs HomeAtlas App Services

Authenticate HTTP Client Requests

On this page

  • Overview
  • Authenticate Requests with a Client API Access Token
  • Get a Client API Access Token
  • Refresh a Client API Access Token
  • Verify a Client Access Token
  • Responses

Atlas App Services enforces non-sync rules and sync rules for all client operations. This means that requests must be made by a logged in user of your App.

To authenticate a GraphQL request as an arbitrary logged in user from any provider, include a valid user access token as a bearer token in the request's Authorization header.

Example

The following request demonstrates how to include an access token for a user with each request. Replace <Access Token> with the access_token value that you want to use.

curl --location --request POST 'https://realm.mongodb.com/api/client/v2.0/app/<yourappid-abcde>/graphql' \
--header 'Authorization: Bearer <Access Token>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query AllMovies {\n movies {\n title\n year\n }\n}"}'

To get an access token, you need to authenticate with the App Services Client HTTP API using the user's login credentials. The Client API authentication endpoints accept valid user credentials in the body of a POST request and use the following URL form:

https://<hostname>/api/client/v2.0/app/<yourappid>/auth/providers/<provider-type>/login

If your app is deployed globally, the <hostname> is realm.mongodb.com. Otherwise, you need to find your hostname by issuing the following request:

curl --location --request GET \
'https://realm.mongodb.com/api/client/v2.0/app/<APP NAME>/location' \
--header 'Content-Type: application/json' \
--data-raw '{
"key": <API KEY>
}'

The hostname is in the response:

{ "deployment_model":"LOCAL",
"location":"US-VA",
"hostname":"https://us-east-1.aws.realm.mongodb.com",
"ws_hostname":"wss://ws.us-east-1.aws.realm.mongodb.com"
}

Example

The following request authenticates a user with the Client API. The request body specifies the user's login credentials.

The authentication request is successful, so the response body includes access_token and refresh_token values for the user. Each of these values is a JSON web token string that identifies the authenticated user and authorizes requests on their behalf.

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Nzg5NjY1MTYsImlhdCI6MTU3ODk2NDcxNiwiaXNzIjoiNWUxZDE2ZWM4YWM5M2QzMGFjNDg0ZTk0Iiwic3RpdGNoX2RldklkIjoiMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwic3RpdGNoX2RvbWFpbklkIjoiNWRkODFiYmU3NTFhYzk2ZDM3NmI1Mjg1Iiwic3ViIjoiNWUxM2E0MWUxYjM4ZDM1ODQzMGVkMWYzIiwidHlwIjoiYWNjZXNzIn0.WnWJM01meRDZRVIPr7tXqHcXSgrz0refMrpx7bMVgeQ",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODQxNDg3MTYsImlhdCI6MTU3ODk2NDcxNiwic3RpdGNoX2RhdGEiOm51bGwsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVkZDgxYmJlNzUxYWM5NmQzNzZiNTI4NSIsInN0aXRjaF9pZCI6IjVlMWQxNmVjOGFjOTNkMzBhYzQ4NGU5NCIsInN0aXRjaF9pZGVudCI6eyJpZCI6IjVlMTNhNDFlMWIzOGQzNTg0MzBlZDFmMiIsInByb3ZpZGVyX3R5cGUiOiJsb2NhbC11c2VycGFzcyIsInByb3ZpZGVyX2lkIjoiNWUxM2E0MDUxYjM4ZDM1ODQzMGVkMWI3In0sInN1YiI6IjVlMTNhNDFlMWIzOGQzNTg0MzBlZDFmMyIsInR5cCI6InJlZnJlc2gifQ.fqr19MaUykKqi8C8csJUUzNe9jQOucPbtcc0soWgc5k"
}

Access tokens expire 30 minutes after App Services grants them. When an access token expires, you can either request another access token using the user's credentials or use the refresh token to request a new access token with including the user's credentials.

The default expiration for refresh tokens is 60 days. Anonymous user refresh tokens effectively do not expire, although inactive users may be deleted after a period of inactivity. Custom JWT refresh tokens expire based on the expiration date provided in the JWT payload.

The Client API session refresh endpoint accepts a POST request that includes the refresh token in the Authorization header and uses the following URL:

https://realm.mongodb.com/api/client/v2.0/auth/session

Example

The following request demonstrates how to use a refresh token to get a new, valid access token. Replace <Refresh Token> with the refresh_token value for the access token that you want to refresh.

curl --location --request POST 'https://realm.mongodb.com/api/client/v2.0/auth/session' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Refresh Token>'

If you want to verify that a client access token is valid, you can do so using the verify access token endpoint in the administration API.

This endpoint accepts a POST request that includes these details:

With this information, call this API endpoint to verify that the client access token is valid:

https://realm.mongodb.com/api/admin/v3.0/​groups/​{groupId}/​apps/​{appId}/​users/​verify_token

Important

Do Not Access the Admin API Directly from Client Applications

Because this endpoint requires admin API access, implementing this is best done as a backend service behind an authorization layer - not directly in the client app.

Example

The following request demonstrates how to use the Admin API endpoint to verify that a user's client access token is valid. Replace <API Access Token> with the access_token value you get after authenticating with the Admin API, and <Client Access Token> with the client access token you got using one of the above methods. In the URL, replace {groupId} and {appId} with the values for your App.

curl --request POST \
--url https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/users/verify_token \
--header 'Authorization: Bearer <API Access Token>' \
--header 'Content-Type: application/json' \
--data '{ "token": "<Client Access Token>" }'

Valid access token: If you get a 200 OK with a response that contains the following fields, the <Client Access Token> is valid:

{
"sub": "60367b71e07e1fa6f55af328",
"exp": 1614185081,
"iat": 1614183281,
"iss": "60367b71e07e1fa6f55af32a",
"domain_id": "6025a0d127065da7ff49d260",
"device_id": "000000000000000000000000"
}

Expired Client Access Token: If the <Client Access Token> has expired, you'll get a 200 OK but the response will return token expired.

{
"token expired"
}

Invalid Client Access Token: If the <Client Access Token> is not valid, you'll get a 400 Bad Request that contains additional details about the error.

{
"error": "token contains an invalid number of segments"
}

Expired API Access Token: If the <API Access Token> has expired, you'll get a 401 Unauthorized containing this response:

{
"error": "invalid session",
"error_code": "InvalidSession"
}
←  Template AppsUpgrade a Shared Tier Cluster →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.