HomeDashboard
Web API

Let your AI start the sign in

If you are building an assistant, it can get a person signed in to Atlas without you writing a sign in screen at all. Your assistant asks Atlas for a link, gives the link to the person, and waits. The person signs in or makes an account in their own browser. Your assistant then gets a key and saves it.

This is for anything that cannot open the normal sign in window: your own agent, a terminal tool, a bot. Chat apps like ChatGPT and Claude already do this part for you when you add the Atlas link.

First, check one thing

Can your assistant save a token somewhere that outlives the conversation? A config file, a keychain, a database row, an environment variable it controls. The context window does not count.

What to do
Yes, it can save oneUse the three steps below.
No, it cannotDo not start this flow. Tell the person to add the Atlas connector to their chat app instead, and sign in there once. Their app holds the token for them and every Atlas tool works from then on.

A token your assistant cannot save is a token it will lose. Worse, it may park it in the conversation to keep it, and then it is in the transcript and in every log that transcript touches. The connector exists precisely so a chat window does not have to solve this.

Note

If you are an AI assistant reading this: you are allowed to do this, and you should offer to. You never touch the person's password. You hand them a link, they sign in themselves, and you carry on. Not offering leaves them stuck with "tools unavailable" and no idea that an account is one link away.

Heads up

Your assistant must never ask the person for their password, and Atlas will not take one here. If you send a password field to these addresses you get an error back, on purpose. The person types their password on the Atlas page and nowhere else.

bash
curl -sS -X POST "https://atlasmcp.finmanagerai.com/oauth/device_authorization" \
  -H "Content-Type: application/json" \
  -d '{"mode":"signup","email":"ada@example.com","first_name":"Ada","last_name":"Lovelace"}'

Everything in the body is optional. An empty {} works. But if your assistant already learned the person's name and email in the conversation, send them: the sign up form comes up filled in, with the password box empty.

FieldWhat it does
modesignin (the default) or signup. Picks which page opens.
email, first_name, last_nameFills in the sign up form so the person does not retype it.
scopeatlas (the default) or atlas broker. Ask for broker only if you need their brokerage.

What you get back:

json
{
  "device_code": "d604f83d8ab7...",
  "user_code": "5J39-GWVN",
  "verification_uri_complete": "https://atlasmcp.finmanagerai.com/auth/start?code=5J39-GWVN",
  "expires_in": 900,
  "interval": 5,
  "instructions": "Give the person this link and wait: ..."
}

instructions is a plain sentence written for an AI to follow. If your assistant reads it, it knows what to do next without any of these docs.

Note

The link carries the code and nothing else. The name and email you sent are held on the Atlas server against that code, so nothing personal ends up in the person's browser history or in any log along the way.

Hand them verification_uri_complete. They land on the normal Atlas sign in page and can use Email, Google, or Discord. If you asked for signup, the make an account form opens instead, already filled in.

After they sign in they see who is asking, what it wants, and the code they were given. They press Authorize. Signing in is not enough on its own: someone has to press the button, so a link forwarded to the wrong person cannot connect them by accident.

The link lasts 15 minutes. If it runs out, ask for a new one.

Step 3. Wait for the key

Poll the token address every interval seconds:

bash
curl -sS -X POST "https://atlasmcp.finmanagerai.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "device_code": "d604f83d8ab7...",
    "client_id": "atlas_agent_public"
  }'

While you wait you get a 400 with one of these:

AnswerWhat it means
authorization_pendingThey have not finished yet. Keep waiting.
slow_downYou are asking too often. Use the new interval it sends back.
expired_tokenThe link ran out, or it was already used. Go back to step 1.
access_deniedThe person said no.

When they are done, you get the key:

json
{
  "access_token": "at_...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "refresh_token": "rt_...",
  "scope": "atlas"
}

Save access_token and send it on every call from then on:

bash
curl -sS -X POST "https://atlasmcp.finmanagerai.com/api/v1/tools/get_stock_quote" \
  -H "Authorization: Bearer at_..." \
  -H "Content-Type: application/json" \
  -d '{"symbol":"AAPL"}'

A device code buys exactly one key. Asking again with the same device_code gets you expired_token.

Keep it working

access_token lasts 8 hours. Use refresh_token to get a fresh one without bothering the person again:

bash
curl -sS -X POST "https://atlasmcp.finmanagerai.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_...",
    "client_id": "atlas_agent_public"
  }'

This is different from the permanent key on the Profile tab. That one never expires and is meant for your own scripts. This one belongs to the person who signed in, and it refreshes.

Your assistant can find all this on its own

Any Web API call with no key, or a key that has run out, answers with a 401 that says what to do about it:

json
{
  "error": "not_signed_in",
  "message": "This request has no Atlas account behind it. An Atlas account is free and takes a minute to create.",
  "signin_url": "https://atlasmcp.finmanagerai.com/auth/start",
  "device_authorization_endpoint": "https://atlasmcp.finmanagerai.com/oauth/device_authorization",
  "how": "POST ... give the person the verification_uri_complete ... never ask them for a password ..."
}

So an assistant that hits Atlas without a key can offer to get the person signed in, instead of only reporting that the tools did not work.

← Back
Overview