--- title: "Troubleshooting" description: "Diagnose and fix common Authentication API problems, from rejected credentials to expired tokens." url: "https://developer-beta.morningstar.com/authentication-api/troubleshooting" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~VHJvdWJsZXNob290aW5nIHwgQXV0aGVudGljYXRpb24gQVBJ,description_~RGlhZ25vc2UgYW5kIGZpeCBjb21tb24gQXV0aGVudGljYXRpb24gQVBJIHByb2JsZW1zLCBmcm9tIHJlamVjdGVkIGNyZWRlbnRpYWxzIHRvIGV4cGlyZWQgdG9rZW5zLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9hdXRoZW50aWNhdGlvbi1hcGkvdHJvdWJsZXNob290aW5nIg,s_7DWYnEndlTjWttqs.png" --- - [APIs](https://developer-beta.morningstar.com/apis) - [API Catalog](https://developer-beta.morningstar.com/api-catalog) - [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp) - [Guides](https://developer-beta.morningstar.com/api-guides) - [Trial Access](https://developer-beta.morningstar.com/trial-access) # Authentication API Generate access tokens that authorize API calls. # Troubleshooting [View Markdown](https://developer-beta.morningstar.com/authentication-api/troubleshooting.md)[Download Markdown](https://developer-beta.morningstar.com/authentication-api/troubleshooting.md) Use this page to diagnose a token request that fails, or a request to another API that is rejected because of its token. Each issue lists the likely causes and how to fix them. For the meaning of an error message, see [Error Messages](https://developer-beta.morningstar.com/authentication-api/error-messages). ## [Before You Start](#before-you-start) Most problems can be traced to one of the following. Check them first. - The token request is a `POST` to `/token/oauth` on the base URL for your region. - The `Authorization` header is `Basic` followed by your Base64-encoded `username:password`. - The username and password are encoded as one string, with the colon between them. - Requests to the other APIs send `Bearer` followed by the `access_token`, and the token is less than 60 minutes old. ## [Reading an Error Response](#reading-an-error-response) A failed token request returns an `error_message` that describes the problem. ```json { "error_message": "Incorrect username or password" } ``` Errors from the other APIs have a different format, with a `statusCode`, an `errorCode`, a `message` and a `requestId`. See the error messages page of the API you are calling. ## [Token Requests](#token-requests) 401 Unauthorized The response is `401` with the message `Incorrect username or password`. - Check your username and password for typos. - Check that you encoded them as one `username:password` string, with the colon between them. - Check that the header is `Authorization: Basic ...`, with a space after `Basic` and no line break in the encoded value. Some tools add a line break when they encode. - If you have not activated your account, check your spam or junk folder for the activation email, or contact your Morningstar account representative. See [Get an Access Token](https://developer-beta.morningstar.com/authentication-api/get-an-access-token#step-1-prepare-your-credentials). --- My Credentials Are Correct but the Request Fails The most common cause is the encoding. - Encode the username and password as a single `username:password` string. Don't encode them separately. - Include the colon before you encode. - Use Base64 encoding, not URL encoding. - Use `echo -n` when you encode on the command line, so that a newline isn't added to the string. See [Get an Access Token](https://developer-beta.morningstar.com/authentication-api/get-an-access-token#step-1-prepare-your-credentials). --- I Haven't Received My Account Activation Email Check your spam or junk folder. If the email isn't there, contact your Morningstar account representative to confirm that the correct email address was registered, and ask for the email to be sent again. --- ## [Using Tokens](#using-tokens) A Request to Another API Returns 401 The API rejected the token. - Check that the header is `Authorization: Bearer {access_token}`. Don't send `Basic` credentials to the other APIs. - Check that you are sending the `access_token` value from the response, with no extra characters or quotation marks. - Check whether the token has expired. Tokens are valid for 60 minutes. - If it has expired, request a new token and retry the request. See [Manage Tokens](https://developer-beta.morningstar.com/authentication-api/manage-tokens#refresh-when-the-token-expires). --- My Token Expired in the Middle of a Job Tokens are valid for 60 minutes, so long jobs can outlast one. - Track the expiry time of the token, using `expires_in`. - Refresh the token before it expires, and check it before each request. - If a request returns `401`, request a new token and retry that request. See [Manage Tokens](https://developer-beta.morningstar.com/authentication-api/manage-tokens#long-running-jobs). --- I Asked for a New Token and Got the Same One If you request a token within 10 minutes of generating one, the API returns the same token. This is expected. Keep using it until it expires. See [Manage Tokens](https://developer-beta.morningstar.com/authentication-api/manage-tokens#token-caching).