Note

Note for developers and agents

Read a workspace's notes over REST or MCP. Connect any of the ways below.

Reading notes

Ways to connect

Agent account with an API key

Create your own agent account and get an API key immediately.

  1. POST https://api.grand-telescope.note.page/v1/agents with {"name": "<your agent name>"}.
  2. Use the api_key from the response as Authorization: Bearer <key> or X-API-Key: <key>, then read notes with GET https://api.grand-telescope.note.page/v1/notes (or the list_notes tool on https://api.grand-telescope.note.page/mcp).

Agent key: signed JWT assertion

Present a JWT signed by your registered key at the token endpoint (RFC 7523).

  1. Register your public key at https://api.grand-telescope.note.page/v1/agents/keys (or register an OAuth client with a jwks and token_endpoint_auth_method private_key_jwt).
  2. POST https://api.grand-telescope.note.page/oauth/token with grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion=<JWT with iss=sub=<agent_id>, aud=https://api.grand-telescope.note.page/oauth/token, exp, jti>.
  3. grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer with assertion=<the same JWT> also works.

Agent key: sign a challenge

Register a public key, from a local file, a KMS, an HSM or a wallet, and sign a challenge to get an access token.

  1. Use any Ed25519, P-256, P-384, P-521, secp256k1 or RSA key: a local file, AWS / GCP / Azure KMS, a YubiKey, TPM or Secure Enclave, or a wallet.
  2. POST https://api.grand-telescope.note.page/v1/agents/keys with {"public_key": <JWK, JWKS, PEM, base64 DER SPKI as KMS GetPublicKey returns, OpenSSH, or a raw key in base64, hex or base58>, "name": "..."} to get an agent_id. For keys that rotate, send {"jwks_uri": "https://...", "kid": "..."} instead.
  3. POST https://api.grand-telescope.note.page/v1/auth/challenge with {"agent_id": "..."}; sign the UTF-8 bytes of the returned message.
  4. POST https://api.grand-telescope.note.page/v1/auth/verify with {"challenge_id": "...", "signature": "..."} to get an access token. The signature can be base64url, base64, hex or base58; ECDSA as r||s or DER (as KMS returns it). Add "kid" if you registered a jwks_uri.

Agent key: sign every request

Skip access tokens: sign each request with your registered key using HTTP Message Signatures (RFC 9421).

  1. Register your public key at https://api.grand-telescope.note.page/v1/agents/keys.
  2. Sign requests with Signature-Input: sig1=("@method" "@target-uri");created=<unix time>;keyid="<agent_id or JWK thumbprint>";alg="ed25519" and Signature: sig1=:<base64 signature>:.

MCP with OAuth (dynamic client registration)

Register an OAuth client on the fly (RFC 7591), then connect to your user's workspace with the authorization code flow.

  1. POST https://api.grand-telescope.note.page/oauth/register with {"client_name": "...", "redirect_uris": ["..."], "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none"}.
  2. Send your user to https://api.grand-telescope.note.page/oauth/authorize with the returned client_id, PKCE (S256) and resource=https://api.grand-telescope.note.page/mcp. They approve with their passkey.
  3. Exchange the code at https://api.grand-telescope.note.page/oauth/token, then read notes with GET https://api.grand-telescope.note.page/v1/notes (or the list_notes tool on https://api.grand-telescope.note.page/mcp).

Workload identity (cloud identity token)

Running on GitHub Actions, Google Cloud, Azure, AWS or SPIFFE? Exchange your platform's signed identity token for an access token. No key to register.

  1. Get an identity token with audience https://api.grand-telescope.note.page:
  2. GitHub Actions (permissions: id-token: write): core.getIDToken("https://api.grand-telescope.note.page"), or curl "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.grand-telescope.note.page" -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN".
  3. Google Cloud: curl -H "Metadata-Flavor: Google" "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.grand-telescope.note.page", or gcloud auth print-identity-token --audiences=https://api.grand-telescope.note.page.
  4. Azure managed identity: curl -H "Metadata: true" "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://api.grand-telescope.note.page" (use the access_token field).
  5. AWS (outbound identity federation enabled): aws sts get-web-identity-token --audience https://api.grand-telescope.note.page --signing-algorithm ES384.
  6. SPIFFE: spire-agent api fetch jwt -audience https://api.grand-telescope.note.page.
  7. Then POST https://api.grand-telescope.note.page/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer and assertion=<identity token>.
  8. Or token exchange: grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token=<identity token>, subject_token_type=urn:ietf:params:oauth:token-type:jwt (or :id_token).
  9. Or client_credentials with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion=<identity token>.
  10. Add a DPoP header to get a DPoP-bound access token, then read notes with GET https://api.grand-telescope.note.page/v1/notes (or the list_notes tool on https://api.grand-telescope.note.page/mcp).

SSH key signature

Prove you hold an SSH key by signing a challenge with ssh-keygen.

  1. POST https://api.grand-telescope.note.page/v1/auth/ssh/challenge with {"public_key": "ssh-ed25519 AAAA..."}.
  2. Sign the nonce: printf '%s' "<nonce>" > challenge.txt && ssh-keygen -Y sign -n note.page -f ~/.ssh/id_ed25519 challenge.txt
  3. POST https://api.grand-telescope.note.page/v1/auth/ssh/verify with {"challenge_id": "...", "signature": "<contents of challenge.txt.sig>"} to get an access token.

HTTP Basic

Send an API key or OAuth client ID and client secret with HTTP Basic.

  1. Authorization: Basic base64(<client_id>:<client_secret>), or base64(:<api_key>).

Backchannel approval (OpenID CIBA)

Ask Note to request approval from a user by username; they approve on their account page.

  1. Register a client first (https://api.grand-telescope.note.page/oauth/register) so you can identify yourself.
  2. POST https://api.grand-telescope.note.page/oauth/bc-authorize with client authentication, login_hint=<your user's Note username>, scope=notes:read and an optional binding_message.
  3. Your user approves at https://note.page/account. Poll https://api.grand-telescope.note.page/oauth/token with grant_type=urn:openid:params:grant-type:ciba and auth_req_id.

Token exchange (acting on behalf of your user)

Combine your own agent identity with an access token your user delegated to you (RFC 8693).

  1. You need a registered agent key (https://api.grand-telescope.note.page/v1/agents/keys) and an access token your user delegated to you.
  2. POST https://api.grand-telescope.note.page/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token=<delegated access token>, subject_token_type=urn:ietf:params:oauth:token-type:access_token, actor_token=<JWT signed by your key with iss=sub=<agent_id>, aud=https://api.grand-telescope.note.page/oauth/token>, actor_token_type=urn:ietf:params:oauth:token-type:jwt.

MCP with OAuth (client ID metadata document)

Connect an MCP client to your user's workspace. The client identifies itself with an HTTPS client ID metadata document.

  1. Connect your MCP client to https://api.grand-telescope.note.page/mcp. Without an access token it answers 401 with a WWW-Authenticate header pointing at https://api.grand-telescope.note.page/.well-known/oauth-protected-resource/mcp.
  2. Authorization server metadata is at https://api.grand-telescope.note.page/.well-known/oauth-authorization-server (client_id_metadata_document_supported: true).
  3. Send your user to https://api.grand-telescope.note.page/oauth/authorize with response_type=code, client_id=<your metadata document URL>, redirect_uri, code_challenge (S256), state and resource=https://api.grand-telescope.note.page/mcp.
  4. Your user signs in with their passkey and approves.
  5. Exchange the code at https://api.grand-telescope.note.page/oauth/token (token_endpoint_auth_method none, or private_key_jwt with the jwks_uri in your document).

Join on the website (email code)

Join the workspace on the website with an email address and the code we send.

  1. Go to https://grand-telescope.note.page/signup, choose email, and enter the code sent to that address.
  2. Your notes are on https://grand-telescope.note.page/account.

API key from your user

Your user creates an API key in their workspace settings and gives it to you.

  1. Ask your user to sign in at https://grand-telescope.note.page/account with their passkey and create an API key.
  2. Send it as Authorization: Bearer <key> (or X-API-Key: <key>), then read notes with GET https://api.grand-telescope.note.page/v1/notes (or the list_notes tool on https://api.grand-telescope.note.page/mcp).

Device code

No browser on your side? Show your user a short code to approve (RFC 8628).

  1. POST https://api.grand-telescope.note.page/oauth/device_authorization with client_id=<any name for your agent> and scope=notes:read.
  2. Tell your user to open https://grand-telescope.note.page/device and enter the user_code (or send them verification_uri_complete).
  3. Poll https://api.grand-telescope.note.page/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code and device_code until it returns an access token.

OAuth with a client your user gives you

If your user gave you a Note client ID (and client secret), use it with the authorization code flow.

  1. Ask your user for the client ID and client secret they created for you.
  2. Run the authorization code flow against https://api.grand-telescope.note.page/oauth/authorize and https://api.grand-telescope.note.page/oauth/token (client_secret_basic or client_secret_post).

Sign-In With Ethereum

Sign an EIP-4361 message with your Ethereum key.

  1. GET https://api.grand-telescope.note.page/v1/auth/siwe/nonce.
  2. Sign an EIP-4361 message for domain grand-telescope.note.page and URI https://grand-telescope.note.page containing that nonce (personal_sign).
  3. POST https://api.grand-telescope.note.page/v1/auth/siwe/verify with {"message": "...", "signature": "0x..."} to get an access token.

Client certificate (mTLS)

Use a self-signed TLS client certificate (RFC 8705).

  1. Create a self-signed client certificate (for example: openssl req -x509 -newkey ed25519 -keyout key.pem -out cert.pem -days 30 -subj /CN=my-agent -nodes).
  2. POST https://mtls.note.page/grand-telescope/v1/agents/certificates while presenting the certificate to register it.
  3. Then GET https://mtls.note.page/grand-telescope/v1/notes with the same certificate, or get a certificate-bound access token from https://mtls.note.page/grand-telescope/oauth/token (grant_type=client_credentials, client_id=<agent_id>).

MCP without OAuth (approval link)

Connect to the open MCP endpoint; when you ask for the pinned note, Note sends your user an approval link (URL-mode elicitation).

  1. Connect an MCP client to https://api.grand-telescope.note.page/mcp/open. No sign-in is needed to connect.
  2. Call get_pinned_note. Note asks your user to approve at a URL; retry after they approve and the tool returns the note.
  3. Clients without URL elicitation get the approval link in the tool result instead; call get_pinned_note again with approval_id once your user approves.

Web Bot Auth

Agents whose operator signs requests and publishes a key directory are recognised automatically.

  1. Sign requests per Web Bot Auth: Signature-Agent naming your operator, and an RFC 9421 signature with tag="web-bot-auth" whose keyid is in the operator's /.well-known/http-message-signatures-directory.
  2. GET https://api.grand-telescope.note.page/v1/notes with that signature.

Sign in on the website (passkey)

Join or sign in on the website with a passkey.

  1. Go to https://grand-telescope.note.page/login and use a passkey.
  2. Your notes are on https://grand-telescope.note.page/account.

Access request

Request access to a user's workspace by username; they approve with one click and a passkey.

  1. POST https://api.grand-telescope.note.page/v1/access-requests with {"username": "<your user's Note username>", "agent_name": "..."}.
  2. Send your user the approve_url from the response.
  3. Poll GET https://api.grand-telescope.note.page/v1/access-requests/<id> until status is "approved"; the response then includes your api_key (shown once).

OAuth client credentials

Register your own OAuth client with no user involved and use the client_credentials grant.

  1. POST https://api.grand-telescope.note.page/oauth/register with {"client_name": "...", "grant_types": ["client_credentials"], "token_endpoint_auth_method": "client_secret_basic"}.
  2. POST https://api.grand-telescope.note.page/oauth/token with grant_type=client_credentials, using the client_id and client_secret.

Reference