Most authentication errors fall into one of six categories: missing or expired session, wrong cookie format, missing headers, IP restrictions, geographic blocks, or wrong API endpoint. Work through this guide in order to identify which applies to you.

1) Understanding the GRVT Authentication Flow

Before troubleshooting, it helps to understand how GRVT authentication works:

· Step 1 — Call POST https://edge.grvt.io/auth/api_key/login with your API key in the request body.

· Step 2 — The response returns a session cookie (gravity=...) in the Set-Cookie response header and your X-Grvt-Account-Id in the response headers (not the response body).

· Step 3 — Include both in every subsequent request to private endpoints.

The login endpoint is on edge.grvt.io. All trading API calls go to trades.grvt.io. These are different hosts — mixing them up is a common cause of 403 errors (see Section 6).

2) 401 Unauthorized — Missing or Expired Session

Cause: You either skipped the login step, your session cookie has expired, or you are not passing the cookie correctly in subsequent requests.

Session expiry by login type: · API Key login: 1 day · Web browser session: 7 days · Mobile app session: 90 days

The exact expiry time is returned alongside the cookie. Read it dynamically rather than hardcoding a fixed duration, as this may change.

Fix:

Do not pass the full Set-Cookie string. Only pass gravity=<value>.

3) 401 on WebSocket Connections

Cause A — Wrong cookie format or missing header. The WebSocket 401 is almost always caused by passing the cookie incorrectly or forgetting the X-Grvt-Account-Id header.

After calling auth/api_key/login, read X-Grvt-Account-Id from the response headers (not the response body). Include it as a header in all trade-related requests and WebSocket connections.

Example headers for WebSocket:

Cause B — API key permissions mismatch. If you receive error code 1000 / HTTP 401 "You need to authenticate prior to using this functionality" on a WebSocket, this means your API key does not have permission for the operation you are attempting — for example, a read-only key trying to place an order, or a transfer-only key trying to trade. This is a permissions error, not a session error. Fix: create a new API key with the correct permissions (e.g. "Trade") from the GRVT UI.

4) IP Whitelist Errors

"IP is not whitelisted"

If you configured an IP whitelist on your API key, login requests must come from one of the whitelisted IPs. Two common gotchas:

· IPv6 addresses: If your server sends requests from an IPv6 address (e.g. 2407:cdc0:...) but you only whitelisted its IPv4 address, the request will be rejected. Check your server's actual outgoing IP — it may be sending IPv6. Add the IPv6 address to your whitelist separately.

· Different IPs across environments: Your local machine and your VPS likely have different IPs. Make sure you are whitelisting the IP that is actually making the API calls in production.

Default whitelist limit: 5 IPs per API key. Institutional clients can request an increase from the GRVT team.

5) Geographic Restrictions

GRVT APIs cannot be accessed from IP addresses located in the United States, United Kingdom, or China. Even with a valid API key and a whitelisted IP, requests from these jurisdictions will be blocked.

Fix:

Note: if you need to authenticate from a restricted region, you may authenticate from a compliant server and reuse the resulting session cookie from your main trading infrastructure. Reach out to GRVT support for guidance on your specific setup.

6) 403 Forbidden — Wrong API Endpoint

A very common issue: clients authenticate successfully via edge.grvt.io but then send trading API calls to edge.grvt.io as well. This returns a Cloudflare 403 block.

The correct split: · edge.grvt.io — authentication only (/auth/api_key/login) · trades.grvt.io — all trading API calls (create_order, cancel_order, account_summary, etc.) · market-data.grvt.io — public market data (no auth required)

If you are getting 403 on trading endpoints despite a successful login, check that you are sending those requests to trades.grvt.io, not edge.grvt.io.

7) Cloudflare Blocks ("Sorry, you have been blocked")

This is separate from the geographic restriction above. Cloudflare's bot-fight protection can block API calls from certain server IPs (particularly AWS datacenter IPs) or if your request volume or pattern triggers its security rules.

Signs you are hitting this: · You receive an HTML page instead of a JSON response · The response contains "This website is using a security service to protect itself from online attacks" · Market data endpoints work but trading endpoints do not

Fix: Contact GRVT support with your server IP and a Cloudflare Ray ID (found in the response headers as CF-Ray). The team can review and clear your IP if appropriate. Note that IP whitelisting at the Cloudflare level is generally reserved for institutional clients.

8) "api_key not found" Error

This error means the API key you are using does not exist in the environment you are calling.

Most common cause: Using a production API key against the dev or testnet endpoint, or vice versa.

· Production: https://edge.grvt.io/auth/api_key/login · Testnet: https://edge.testnet.grvt.io/auth/api_key/login

API keys are environment-specific. A key created on mainnet will not work on testnet, and vice versa.

9) 1001 / 403 "You are not authorized to access this functionality"

This error means your API key does not have the required permission scope for the endpoint you are calling.

Common causes: · API key is set to "Read Only" but you are trying to place or cancel orders · API key is set to "Transfer Only" but you are trying to trade · You are trying to use a feature (e.g. RPI orders) that requires your sub-account to be specifically whitelisted by GRVT

Fix: Generate a new API key with the correct permission (e.g. "Trade") from the GRVT UI. For RPI whitelisting, contact GRVT support — whitelisting must be applied per sub-account.

FAQs

Q: I authenticated successfully but WebSocket still returns 401. What do I check first?

Confirm you are passing Cookie: gravity=<value> (not the full Set-Cookie string) and that you are also including X-Grvt-Account-Id as a header, taken from the response headers of your login call — not the response body.

Q: My authentication worked yesterday but fails today. Why?

API key sessions expire after 1 day. Re-authenticate by calling auth/api_key/login again and use the new cookie.

Q: I whitelisted my IP but still get "IP is not whitelisted". What's wrong?

Check whether your server is making requests from an IPv6 address instead of the IPv4 you whitelisted. Run a check on your server's outgoing IP and whitelist the IPv6 address separately if needed.

Q: Can I access the GRVT API from a US, UK, or China-based VPS?

No. GRVT applies geographic restrictions to these regions. Use a server located outside these regions and ensure that IP is added to your API key whitelist.

Q: My login returns 200 but I get blocked on every trading endpoint. What's happening?

You are likely sending trading API calls to edge.grvt.io instead of trades.grvt.io. Authentication is on edge.grvt.io; all trading calls must go to trades.grvt.io.

Q: What if I keep getting Cloudflare "Sorry, you have been blocked" on trading endpoints?

This is typically a bot-fight protection trigger on your server IP. Contact GRVT support with your IP address and the CF-Ray value from the response headers. Do not attempt to work around Cloudflare blocks without engaging support.

Q: My API key permissions look correct but I still get 1001 / 403.

If this happens on a specific feature like RPI orders, that feature requires sub-account-level whitelisting, not just a permission flag on the API key. Contact GRVT support and specify which sub-account needs to be whitelisted.