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 dashboard.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.

API Keys section in the Solvice Dashboard

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": [...]
  }'

Authentication Errors

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

{
  "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 request

Solution: 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

403 Forbidden - Insufficient Permissions

429 Too Many Requests

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:

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' });
  }
});

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:

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

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:

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: [...]
});

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'

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

Platform

VRP API

​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