Authentication - Solvice Docs

Overview

The Solvice Platform uses API key authentication to secure access to all optimization endpoints. Every request to our solvers requires a valid API key included in the request headers.

All API communications are encrypted using HTTPS to ensure your data and credentials remain secure during transmission.

Getting Your API Key

Create your account at platform.solvice.io if you haven’t already.

New accounts receive a 14-day free trial with full access to all solver capabilities.

Navigate to API Keys

Once logged in, go to Settings → API Keys in your dashboard.

Solvice Dashboard API Keys management interface showing the Create API Key button

Generate a new key

Click Create API Key and provide a descriptive name for your key (e.g., “Production VRP Integration”).

Store your API key securely. For security reasons, you won’t be able to view the full key again after creation.

Configure key permissions

Select which solvers and operations this key can access:

Solver access: VRP, FILL, CREATE, TASK, CLUST
Operations: Solve, Evaluate, Suggest, Status, Solution, Explanation

Follow the principle of least privilege - only grant permissions required for your specific use case.

Using Your API Key

Include your API key in the Authorization header of every request to Solvice APIs.

Authentication Header Format

Authorization: YOUR_API_KEY

The API key should be sent directly in the Authorization header without any prefix like “Bearer” or “Basic”.

Request Examples

curl -X POST 'https://api.solvice.io/v2/vrp/solve' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vehicles": [...],
    "jobs": [...],
    "objectives": [...]
  }'

const response = await fetch('https://api.solvice.io/v2/vrp/solve', {
  method: 'POST',
  headers: {
    'Authorization': process.env.SOLVICE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
});

if (!response.ok) {
  throw new Error(`API request failed: ${response.status}`);
}

const result = await response.json();

import os
import requests

api_key = os.environ.get('SOLVICE_API_KEY')

response = requests.post(
    'https://api.solvice.io/v2/vrp/solve',
    headers={
        'Authorization': api_key,
        'Content-Type': 'application/json'
    },
    json=request_data
)

if response.status_code != 200:
    raise Exception(f'API request failed: {response.status_code}')

result = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.solvice.io/v2/vrp/solve"))
    .header("Authorization", System.getenv("SOLVICE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(requestJson))
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", 
    Environment.GetEnvironmentVariable("SOLVICE_API_KEY"));

var response = await client.PostAsJsonAsync(
    "https://api.solvice.io/v2/vrp/solve", 
    requestData
);

response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<SolveResponse>();

Authentication Errors

When authentication fails, the API returns specific error codes to help diagnose the issue:

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "Please check your Authorization header"
  }
}

Common Authentication Issues

401 Unauthorized - Missing API Key

Problem: No API key provided in the requestSolution: Ensure the Authorization header is included in your request

# ❌ Missing Authorization header
curl -X POST 'https://api.solvice.io/v2/vrp/solve'

# ✅ Correct
curl -X POST 'https://api.solvice.io/v2/vrp/solve' \
  -H 'Authorization: YOUR_API_KEY'

401 Unauthorized - Invalid API Key

Problem: The provided API key is invalid or has been revokedSolution:

Verify you’re using the correct API key
Check if the key has been accidentally truncated
Ensure the key hasn’t been revoked in your dashboard

403 Forbidden - Insufficient Permissions

Problem: Your API key doesn’t have permission for the requested operationSolution: Check your key’s permissions in the dashboard and ensure it has access to:

The specific solver (VRP, FILL, etc.)
The operation type (solve, evaluate, suggest)

429 Too Many Requests

Problem: You’ve exceeded your rate limitSolution:

Implement exponential backoff in your retry logic
Check your current rate limits in the dashboard
Consider upgrading your plan for higher limits

Security Best Practices

Environment Variables

Never hardcode API keys in your source code. Use environment variables instead:

.env

SOLVICE_API_KEY=your_api_key_here

Add .env files to your .gitignore to prevent accidental commits

Key Rotation

Regularly rotate your API keys, especially for production environments:

Set up a rotation schedule (e.g., every 90 days)
Update keys during maintenance windows
Keep the previous key active briefly during transition

Separate Keys by Environment

Use different API keys for different environments:

const apiKey = process.env.NODE_ENV === 'production' 
  ? process.env.SOLVICE_PROD_KEY
  : process.env.SOLVICE_DEV_KEY;

Monitor Key Usage

Regularly review your API key usage in the dashboard:

Check for unexpected usage patterns
Monitor which endpoints are being called
Set up alerts for unusual activity

Restrict Key Permissions

Apply the principle of least privilege:

Development keys: Limited to non-production solvers
Production keys: Only required solvers and operations
CI/CD keys: Read-only access for testing

Server-Side Proxy Pattern

For web applications, implement a server-side proxy to keep your API keys secure:

Node.js Express
Python Flask
Client-Side

server.js

const express = require('express');
const app = express();

// Never expose API keys to client-side code
const SOLVICE_API_KEY = process.env.SOLVICE_API_KEY;

app.post('/api/solve', async (req, res) => {
  try {
    const response = await fetch('https://api.solvice.io/v2/vrp/solve', {
      method: 'POST',
      headers: {
        'Authorization': SOLVICE_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(req.body)
    });
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.py

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
SOLVICE_API_KEY = os.environ.get('SOLVICE_API_KEY')

@app.route('/api/solve', methods=['POST'])
def solve():
    try:
        response = requests.post(
            'https://api.solvice.io/v2/vrp/solve',
            headers={
                'Authorization': SOLVICE_API_KEY,
                'Content-Type': 'application/json'
            },
            json=request.json
        )
        return jsonify(response.json()), response.status_code
    except Exception as e:
        return jsonify({'error': 'Internal server error'}), 500

frontend.js

// Client makes requests to your server, not directly to Solvice
const response = await fetch('/api/solve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(optimizationRequest)
});

// No API key needed on client side
const result = await response.json();

Rate Limiting

Solvice implements rate limiting to ensure fair usage and platform stability:

Rate Limit Headers
Handling Rate Limits

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

X-RateLimit-Limit

integer

Maximum requests allowed in the current window

X-RateLimit-Remaining

integer

Number of requests remaining in the current window

X-RateLimit-Reset

integer

Unix timestamp when the rate limit window resets

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = resetTime 
        ? (parseInt(resetTime) * 1000) - Date.now()
        : Math.pow(2, i) * 1000; // Exponential backoff
      
      console.log(`Rate limited. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

SDK Authentication

Our official SDKs handle authentication details for you:

JavaScript/TypeScript
Python
Java

import { SolviceClient } from '@solvice/sdk';

const client = new SolviceClient({
  apiKey: process.env.SOLVICE_API_KEY,
  // SDK handles all authentication headers
});

const result = await client.vrp.solve({
  vehicles: [...],
  jobs: [...]
});

from solvice import SolviceClient

client = SolviceClient(
    api_key=os.environ.get('SOLVICE_API_KEY')
)

result = client.vrp.solve(
    vehicles=[...],
    jobs=[...]
)

SolviceClient client = SolviceClient.builder()
    .apiKey(System.getenv("SOLVICE_API_KEY"))
    .build();

SolveResponse result = client.vrp().solve(
    SolveRequest.builder()
        .vehicles(vehicles)
        .jobs(jobs)
        .build()
);

Testing Authentication

Use our test endpoint to verify your API key is working correctly:

curl 'https://api.solvice.io/v2/auth/verify' \
  -H 'Authorization: YOUR_API_KEY'

{
  "valid": true,
  "key_name": "Production VRP Integration",
  "permissions": {
    "solvers": ["vrp", "fill"],
    "operations": ["solve", "status", "solution"]
  },
  "rate_limit": {
    "requests_per_hour": 1000,
    "concurrent_jobs": 10
  }
}

Next Steps

Quick Start

Start optimizing routes with your API key

API Reference

Explore all available endpoints

SDKs

Use our official SDK libraries

Dashboard

Manage your API keys and usage

​Overview

​Getting Your API Key

​Using Your API Key

​Authentication Header Format

​Request Examples

​Authentication Errors

​Common Authentication Issues

​Security Best Practices

​Server-Side Proxy Pattern

​Rate Limiting

​SDK Authentication

​Testing Authentication

​Next Steps

Quick Start

API Reference

SDKs

Dashboard

Overview

Getting Your API Key

Using Your API Key

Authentication Header Format

Request Examples

Authentication Errors

Common Authentication Issues

Security Best Practices

Server-Side Proxy Pattern

Rate Limiting

SDK Authentication

Testing Authentication

Next Steps