Skip to main content

API Authentication

All API requests to Taktikal require authentication using HTTP Basic Authentication. This page explains how to properly authenticate your requests.

Understanding Basic Authentication​

HTTP Basic Authentication is a simple authentication scheme built into the HTTP protocol. It requires sending a username and password with each request.

How Basic Auth Works​

  1. Credentials: Combine your username and password with a colon (:) between them
  2. Encoding: Encode the combined string using Base64 encoding
  3. Header: Send the encoded string in the Authorization header prefixed with Basic

Example:

Username: mycompanykey
Password: api-1234567890abcdef
Combined: mycompanykey:api-1234567890abcdef
Base64 Encoded: bXljb21wYW55a2V5OmFwaS0xMjM0NTY3ODkwYWJjZGVm
Authorization Header: Basic bXljb21wYW55a2V5OmFwaS0xMjM0NTY3ODkwYWJjZGVm

Taktikal Authentication Credentials​

For Taktikal API authentication:

  • Username: Your companyKey
  • Password: Your API-Key

Where to Find Your Credentials​

You can find your authentication credentials in the Taktikal settings:

Implementation Examples​

Raw HTTP Request​

POST /signing-processes HTTP/1.1
Host: onboarding.taktikal.is
Authorization: Basic MTNhNGU3YjdlNzI0OmFwaS0zZmY0MDkxZDFkOWU0NzQwYmJiMTNkMWI2MmZi
Content-Type: application/json

{
  "documentName": "Contract.pdf",
  "document": "base64encodeddocument..."
}

cURL​

curl -X POST "https://onboarding.taktikal.is/api/signing-processes" \
  -H "Authorization: Basic MTNhNGU3YjdlNzI0OmFwaS0zZmY0MDkxZDFkOWU0NzQwYmJiMTNkMWI2MmZi" \
  -H "Content-Type: application/json" \
  -d '{
    "documentName": "Contract.pdf",
    "document": "base64encodeddocument..."
  }'

JavaScript (Axios)​

const axios = require('axios');

const response = await axios.post('https://onboarding.taktikal.is/api/signing-processes', {
  documentName: 'Contract.pdf',
  document: 'base64encodeddocument...'
}, {
  headers: {
    'Authorization': 'Basic MTNhNGU3YjdlNzI0OmFwaS0zZmY0MDkxZDFkOWU0NzQwYmJiMTNkMWI2MmZi',
    'Content-Type': 'application/json'
  }
});

JavaScript (Fetch)​

const response = await fetch('https://onboarding.taktikal.is/api/signing-processes', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic MTNhNGU3YjdlNzI0OmFwaS0zZmY0MDkxZDFkOWU0NzQwYmJiMTNkMWI2MmZi',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentName: 'Contract.pdf',
    document: 'base64encodeddocument...'
  })
});

C# (RestSharp)​

using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://onboarding.taktikal.is/api/");
client.Authenticator = new HttpBasicAuthenticator("YOUR_COMPANYKEY", "YOUR_API_KEY");

var request = new RestRequest("signing-processes", Method.Post);
request.AddJsonBody(new {
    documentName = "Contract.pdf",
    document = "base64encodeddocument..."
});

var response = await client.ExecuteAsync(request);

Python (Requests)​

import requests
import base64

# Encode credentials
credentials = base64.b64encode(b'YOUR_COMPANYKEY:YOUR_API_KEY').decode('utf-8')

response = requests.post(
    'https://onboarding.taktikal.is/api/signing-processes',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json={
        'documentName': 'Contract.pdf',
        'document': 'base64encodeddocument...'
    }
)

Common Authentication Issues​

Invalid Credentials Error (401)​

If you receive a 401 Unauthorized error:

  1. Verify your credentials - Check that your companyKey and API-Key are correct
  2. Check the environment - Make sure you're using the right credentials for the right environment (dev vs. production)
  3. Verify Base64 encoding - Ensure your credentials are properly Base64 encoded
  4. Check the header format - The header should be Authorization: Basic <encoded-credentials>

Missing Authorization Header​

Always include the Authorization header in your requests. Some endpoints may work without authentication, but it's recommended to always include it for security.

Environment Mismatch​

Make sure you're using:

  • Development credentials with https://onboardingdev.taktikal.is/api/
  • Production credentials with https://onboarding.taktikal.is/api/

Security Best Practices​

  1. Never expose credentials - Don't hardcode API keys in client-side code or public repositories
  2. Use environment variables - Store credentials in environment variables or secure configuration files
  3. Use HTTPS only - Always use HTTPS endpoints to ensure credentials are encrypted in transit

Testing Authentication​

You can test your authentication by making a simple request to any API endpoint. If authentication fails, you'll receive a 401 Unauthorized response.

Example test request:

curl -X GET "https://onboarding.taktikal.is/api/management/apikeys" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS"

If successful, you should receive a response with info on your API keys.