Gridline

Build with the API

Authentication

Sessions for people, API keys for programs, and how a token stays alive.

Every request to Gridline says who is asking, in one header: Authorization: Bearer <token>. There are two kinds of token, for two kinds of caller.

A sessionAn API key
ForA person using the dashboard, or your own app signing someone inA script, a server or an AI agent
Looks likeA long token that expires in 15 minutesgl_live_…, valid until revoked
Can reachEverything the person's role allowsOnly what its scopes allow, never more than its owner
Made bySigning inA person, in Developers → API keys

Sign in

POST/auth/loginPublic. 10 attempts a minute per address.
curl https://gridline-data-analysis-app.duckdns.org/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "nino@acme.com", "password": "a long passphrase" }'
Response
{
  "accessToken": "eyJhbGciOi…",
  "refreshToken": "q3Zk…",
  "tokenType": "Bearer",
  "expiresIn": 900
}
  • accessToken is what you send in the Authorization header. It lasts expiresIn seconds (15 minutes).
  • refreshToken is what you keep, to get a new access token without asking for the password again. It lasts 30 days.

When sign-in is refused

AnswerMeaning
401"Invalid email or password." It is the same answer for a wrong password and for an address that has no account, on purpose.
403The password was right but the account cannot sign in: it is not activated yet, it was disabled, or its company is not active.
429Too many attempts from this address. Wait a minute.

Keep a session alive

POST/auth/refreshPublic.

When the access token expires, trade the refresh token for a new pair:

curl
curl https://gridline-data-analysis-app.duckdns.org/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "q3Zk…" }'

Sign out

POST/auth/logoutSend the refreshToken.

Ends that session immediately. The access token still expires on its own clock.

Other ways to sign in

  • Google. POST /auth/oauth/google/url returns the Google address to send the person to. When they return, you trade a one-time code at POST /auth/oauth/exchange. See Your account.
  • An invitation. POST /auth/accept-invite with the emailed token and a password creates the person's login and signs them in.

Your role is checked every time

A token says who you are, not what you may do. On every request Gridline reads your role, your status and your company's status from the database. If an admin demotes you, removes you, or the company is suspended, your very next request reflects it. There is no list of revoked tokens to wait on.

If something is wrong with the token

AnswerMeaning
401No token, a bad or expired token, a revoked API key, or the owner is gone. The message is deliberately the same for all of these.
403The token is fine but not allowed here: the role is too low, the API key lacks a scope, or the company is suspended.