Skip to main content

API Keys

API Keys grant access to Syndica's APIs and cloud products. Each key can be configured with fine-grained controls including rate limits, IP/origin restrictions, and method-specific access.

Key Features:

  • Time-to-live (TTL) up to 1,000 days
  • Global access restrictions (IP addresses, origin domains)
  • Custom rate limits per service (solana-mainnet, solana-devnet, chainstream)
  • Method-specific and credential-wide limits
  • WebSocket connection limits

API Keys are managed at the Stack level. From your Stack's homepage, navigate to the API Keys page to view, create, and manage your credentials.

Create an API Key​

Setting up an API key is straightforward, and you can have multiple keys at once to suit different needs of your DApp. When you first sign up, Syndica automatically creates a default API key to help you get started quickly.

To create a new API key:

  1. Navigate to the API Keys page from your Stack's homepage
  2. Click New API Key in the top right corner
  3. Complete the Create API Key Wizard:

Step 1: The Basics​

Enter a unique nickname and set a Time to Live (TTL) with a maximum of 1,000 days.

Enter API key basics
Enter API key basics

Step 2: Global Settings (Optional)​

Restrict requests from specific IP addresses or origin domains. This is useful for dev keys that should only be accessible by your development team, or when you know requests will only come from particular IPs or domains.

Configure global settings
Configure global settings

IP Address Restrictions:

  • Limit requests to specified IP addresses
  • If no IP is specified, requests from all IP addresses are accepted

Origin Domain Restrictions:

  • Limit requests to specified domains
  • Wildcard subdomains are supported (e.g., *.example.com)
  • If no domain is specified, requests from all origins are accepted

Step 3: Custom Rate Limits (Optional)​

Custom rate limits provide precise control over API key access. You can set credential-wide limits or restrict access to specific methods. See the Custom Rate Limits guide for detailed examples and use cases.

Check Account Limits

Before configuring custom rate limits, review your account-wide limits on the Account Limits page.

Selecting a Service:

Enable custom rate limits
Enable custom rate limits

Syndica supports three services for request limiting:

  • solana-mainnet
  • solana-devnet
  • chainstream (requires Scale Mode or higher with ChainStream enabled)

Select the service(s) relevant to this credential.

Step 4: Review and Create​

Review your selections and click Create API Key to finish. You'll be taken to the credential's detail page where you can see:

  • Expiration date
  • The API key token
  • RPC and WebSocket limits
  • A getting started guide
Review API key settings
Review API key settings

Revoke an API Key​

If you believe a credential has been compromised or want to revoke its access for any reason, you can immediately disable it.

To revoke an API key:

  1. Navigate to the credential's detail page
  2. Click Revoke in the upper right corner
  3. Confirm the action
Immediate Effect

Revoking a credential immediately causes all API calls using that credential to fail. Update your DApp with a new credential before revoking the old one.

Set Global Access Restrictions​

Global access restrictions limit which IP addresses or domains can use the API key.

During API key creation:

  1. In the Global Settings step, configure:
    • IP Address Restrictions: Enter specific IP addresses (if no IP specified, all IPs accepted)
    • Origin Domain Restrictions: Enter domains with optional wildcard subdomains (if no domain specified, all origins accepted)
  2. Continue to next step

Use cases:

  • Development keys limited to your team's office IP range
  • Production keys restricted to your server IPs
  • Frontend keys restricted to your application domains

Configure Custom Rate Limits​

Custom rate limits allow granular control over how the API key can be used. You can set limits at the credential level or for specific methods.

For RPC Services (solana-mainnet/solana-devnet):

Custom RPC request limits
Custom RPC request limits
  1. Credential-Wide Limits: Set overall RPS limit and limit per IP address
Set limits for all methods
Set limits for all methods
  1. Method-Specific Limits: Click "Add RPC Method" or "Add Subscription Method" to set limits for individual methods
Set limits for specific RPC methods
Set limits for specific RPC methods

For ChainStream:

Set limits for ChainStream
Set limits for ChainStream

Similar to RPC services, you can set credential-wide and method-specific limits for ChainStream subscriptions.

ChainStream Requirements

Ensure ChainStream is enabled on your account before configuring limits. Visit the ChainStream section to enable it.

Set WebSocket Connection Limits​

Control the maximum number of WebSocket connections allowed by the credential.

WebSocket connection limits
WebSocket connection limits

Configuration options:

  • Maximum WebSocket Connections: Overall connection limit for the credential
  • Maximum Connections Per IP: Limit connections from a single IP address
Connection Limit Rules
  • Setting either value to zero blocks all WebSocket traffic
  • Connection limits must be below your account maximum
  • Applies to both Solana WebSocket methods and ChainStream

Set Method-Specific Limits​

Method-specific limits provide the finest level of control, allowing you to set different limits for each RPC method or subscription type.

To add method-specific limits:

  1. During rate limit configuration, click "Add RPC Method" or "Add Subscription Method"
  2. Select the method from the dropdown
  3. Enter values for:
    • Total Rate Limit: Overall requests per second for this method
    • Rate Limit Per IP: Requests per second per IP address (optional)
  4. Click Add and repeat for additional methods
  5. Set limits for unspecified methods (any method not explicitly configured)

Important considerations:

  • Unspecified method limits default to 0 (blocked)
  • Method-specific limits override credential-wide limits
  • Each method can have different limits based on its resource intensity

FAQ and Troubleshooting​

Which authentication method should I use?

Both methods work identically—choose based on your use case:

  • URL-embedded is simpler for testing with tools like cURL or Postman.
  • Header-embedded keeps your key out of URL paths, which may be preferable for logging and monitoring systems.
Can I use the same API key for both mainnet and devnet?

Yes. Your API key works across both mainnet and devnet. Simply change the endpoint URL while keeping the same key.

I'm getting a 401 Unauthorized error. What's wrong?

This means your API key is missing or invalid. Check that:

  • You copied the entire key from your dashboard (no spaces or line breaks).
  • You're using the correct format: /api-key/YOUR_KEY in the URL or X-Syndica-Api-Key: YOUR_KEY in the header.
  • Your key hasn't been revoked or deleted in the dashboard.

See the Error Handling guide for more troubleshooting tips.

How do I know if I'm hitting rate limits?

Rate limit responses return HTTP 429 status codes. You can monitor your usage in the RPC Analytics dashboard. See Observability to learn how to inspect logs and metrics when diagnosing throttling, review Rate Limits and plans/pricing for plan-specific limits, or configure custom rate limits per API key.

What You Can Do Next​