Authentication API

Generate access tokens that authorize API calls.

Get an Access Token

This page walks through getting an access token, one step at a time. For the ideas behind it, see Core Concepts.

Request Overview

To get a token, send a POST request to the token endpoint.

POST /token/oauth

Use the base URL for your region.

Region	Base URL
Americas	`https://www.us-api.morningstar.com`
APAC	`https://www.apac-api.morningstar.com`
EMEA	`https://www.emea-api.morningstar.com`

The request needs one header, and has no body.

Header	Value
`Authorization`	`Basic {Base64-encoded username:password}`

Step 1: Prepare Your Credentials

The API uses HTTP Basic authentication. Combine your username and password into one string, with a colon between them, and Base64-encode the string.

echo -n "username:password" | base64

Encode them as a single username:password string. A common mistake is to encode the username and the password separately. The colon must be included before you encode.

Many HTTP clients can do the encoding for you. For example, curl does it when you use the --user option.

Step 2: Request a Token

Send the request with your encoded credentials in the Authorization header.

curl --request POST \
  --url "https://www.us-api.morningstar.com/token/oauth" \
  --header "Authorization: Basic {Base64-encoded username:password}"

Step 3: Read the Response

A successful request returns 200 OK with your token.

{
  "access_token": "eyJhbGciOiJ...",
  "expires_in": 3599,
  "token_type": "Bearer"
}

Property	Description
`access_token`	The signed JWT. Use it as a `Bearer` token in subsequent requests.
`expires_in`	The number of seconds until the token expires. After that, request a new token.
`token_type`	The token type. The value is always `Bearer`.

If the credentials aren't accepted, the API returns 401 Unauthorized with an error_message.

{
  "error_message": "Incorrect username or password"
}

See Error Messages and Troubleshooting.

Step 4: Use the Token

Include the access_token as a Bearer token in the Authorization header of every request to the other APIs.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/..." \
  --header "Authorization: Bearer {access_token}"

Use the same token for as many requests as you like until it expires. See Manage Tokens.

Next Steps

Manage Tokens explains how to reuse and refresh tokens.
API Inputs is a quick reference for the request and the response.