Authentication

The MagFi API uses bearer token authentication. You can authenticate using either a short-lived JWT token or a persistent API key.

Choosing an Authentication Method

Use Case	Method	Token Lifespan
Server-to-server integrations	API Key	Permanent (until revoked)
User-facing applications	JWT Token	1 hour
Testing & development	Either	-

Environment Setup

All code examples in this guide use a BASE_URL variable. Set this to your target environment:

• Production: https://api.magfi.net
• Sandbox: https://api.sandbox.magfi.dev

---

JWT Token Authentication

JWT tokens are ideal for user-facing applications where you authenticate as a specific user. Tokens expire after 1 hour.

Steps

1. Call POST /auth/login with email and password
2. Receive a token in the response
3. Include token in Authorization: Bearer <token> header for subsequent requests
4. Request a new token when the current one expires (after 1 hour)

Example: Login and Get Token

cURL

BASE_URL="https://api.magfi.net"

# Step 1: Login to get JWT token
curl -X POST $BASE_URL/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

# Response:
# {
#   "token": "<your-jwt-token>"
# }

JavaScript

const BASE_URL = "https://api.magfi.net";

// Step 1: Login to get JWT token
async function login(email, password) {
  try {
    const response = await fetch(`${BASE_URL}/auth/login`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: email,
        password: password,
      }),
    });

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

    const data = await response.json();
    return data.token;
  } catch (error) {
    console.error('Login error:', error);
    throw error;
  }
}

// Usage
const token = await login('[email protected]', 'your-password');
console.log('JWT Token:', token);

Python

import requests

BASE_URL = "https://api.magfi.net"

# Step 1: Login to get JWT token
def login(email, password):
    try:
        response = requests.post(
            f"{BASE_URL}/auth/login",
            json={
                "email": email,
                "password": password
            }
        )
        response.raise_for_status()
        return response.json()["token"]
    except requests.exceptions.RequestException as e:
        print(f"Login error: {e}")
        raise

# Usage
token = login("[email protected]", "your-password")
print(f"JWT Token: {token}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const BASE_URL = "https://api.magfi.net"

type LoginRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

type LoginResponse struct {
    Token string `json:"token"`
}

// Step 1: Login to get JWT token
func login(email, password string) (string, error) {
    loginReq := LoginRequest{
        Email:    email,
        Password: password,
    }

    jsonData, err := json.Marshal(loginReq)
    if err != nil {
        return "", fmt.Errorf("error marshaling request: %w", err)
    }

    resp, err := http.Post(
        BASE_URL+"/auth/login",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        return "", fmt.Errorf("login request failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return "", fmt.Errorf("login failed with status: %d", resp.StatusCode)
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return "", fmt.Errorf("error reading response: %w", err)
    }

    var loginResp LoginResponse
    if err := json.Unmarshal(body, &loginResp); err != nil {
        return "", fmt.Errorf("error parsing response: %w", err)
    }

    return loginResp.Token, nil
}

// Usage
func main() {
    token, err := login("[email protected]", "your-password")
    if err != nil {
        fmt.Printf("Login error: %v\n", err)
        return
    }
    fmt.Printf("JWT Token: %s\n", token)
}

Rust

use serde::{Deserialize, Serialize};
use reqwest;

const BASE_URL: &str = "https://api.magfi.net";

#[derive(Serialize)]
struct LoginRequest {
    email: String,
    password: String,
}

#[derive(Deserialize)]
struct LoginResponse {
    token: String,
}

// Step 1: Login to get JWT token
async fn login(email: &str, password: &str) -> Result<String, Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let login_req = LoginRequest {
        email: email.to_string(),
        password: password.to_string(),
    };

    let response = client
        .post(&format!("{}/auth/login", BASE_URL))
        .json(&login_req)
        .send()
        .await?;

    if !response.status().is_success() {
        return Err(format!("Login failed with status: {}", response.status()).into());
    }

    let login_resp: LoginResponse = response.json().await?;
    Ok(login_resp.token)
}

// Usage
#[tokio::main]
async fn main() {
    match login("[email protected]", "your-password").await {
        Ok(token) => println!("JWT Token: {}", token),
        Err(e) => eprintln!("Login error: {}", e),
    }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;

public class MagFiAuth {
    private static final String BASE_URL = "https://api.magfi.net";
    private static final Gson gson = new Gson();

    static class LoginRequest {
        String email;
        String password;

        LoginRequest(String email, String password) {
            this.email = email;
            this.password = password;
        }
    }

    static class LoginResponse {
        String token;
    }

    // Step 1: Login to get JWT token
    public static String login(String email, String password) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        LoginRequest loginReq = new LoginRequest(email, password);
        String requestBody = gson.toJson(loginReq);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/auth/login"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

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

        if (response.statusCode() != 200) {
            throw new Exception("Login failed with status: " + response.statusCode());
        }

        LoginResponse loginResp = gson.fromJson(response.body(), LoginResponse.class);
        return loginResp.token;
    }

    // Usage
    public static void main(String[] args) {
        try {
            String token = login("[email protected]", "your-password");
            System.out.println("JWT Token: " + token);
        } catch (Exception e) {
            System.err.println("Login error: " + e.getMessage());
        }
    }
}

Ruby

require 'net/http'
require 'json'
require 'uri'

BASE_URL = 'https://api.magfi.net'

# Step 1: Login to get JWT token
def login(email, password)
  uri = URI("#{BASE_URL}/auth/login")
  
  request = Net::HTTP::Post.new(uri)
  request['Content-Type'] = 'application/json'
  request.body = {
    email: email,
    password: password
  }.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  unless response.is_a?(Net::HTTPSuccess)
    raise "Login failed with status: #{response.code}"
  end

  data = JSON.parse(response.body)
  data['token']
rescue StandardError => e
  puts "Login error: #{e.message}"
  raise
end

# Usage
token = login('[email protected]', 'your-password')
puts "JWT Token: #{token}"

Example: Using the JWT Token

cURL

# Step 2: Use the JWT token in subsequent requests
TOKEN="<your-jwt-token>"

curl -X GET $BASE_URL/accounts \
  -H "Authorization: Bearer $TOKEN"

JavaScript

// Step 2: Use the JWT token in subsequent requests
async function getAccounts(token) {
  try {
    const response = await fetch(`${BASE_URL}/accounts`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    });

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

    const accounts = await response.json();
    return accounts;
  } catch (error) {
    console.error('Request error:', error);
    throw error;
  }
}

// Usage
const accounts = await getAccounts(token);
console.log('Accounts:', accounts);

Python

# Step 2: Use the JWT token in subsequent requests
def get_accounts(token):
    try:
        response = requests.get(
            f"{BASE_URL}/accounts",
            headers={"Authorization": f"Bearer {token}"}
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        raise

# Usage
accounts = get_accounts(token)
print(f"Accounts: {accounts}")

Go

// Step 2: Use the JWT token in subsequent requests
func getAccounts(token string) ([]byte, error) {
    req, err := http.NewRequest("GET", BASE_URL+"/accounts", nil)
    if err != nil {
        return nil, fmt.Errorf("error creating request: %w", err)
    }

    req.Header.Set("Authorization", "Bearer "+token)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("request failed with status: %d", resp.StatusCode)
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("error reading response: %w", err)
    }

    return body, nil
}

// Usage
accounts, err := getAccounts(token)
if err != nil {
    fmt.Printf("Request error: %v\n", err)
    return
}
fmt.Printf("Accounts: %s\n", accounts)

Rust

// Step 2: Use the JWT token in subsequent requests
async fn get_accounts(token: &str) -> Result<String, Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();

    let response = client
        .get(&format!("{}/accounts", BASE_URL))
        .header("Authorization", format!("Bearer {}", token))
        .send()
        .await?;

    if !response.status().is_success() {
        return Err(format!("Request failed with status: {}", response.status()).into());
    }

    let body = response.text().await?;
    Ok(body)
}

// Usage
match get_accounts(&token).await {
    Ok(accounts) => println!("Accounts: {}", accounts),
    Err(e) => eprintln!("Request error: {}", e),
}

Java

// Step 2: Use the JWT token in subsequent requests
public static String getAccounts(String token) throws Exception {
    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(BASE_URL + "/accounts"))
        .header("Authorization", "Bearer " + token)
        .GET()
        .build();

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

    if (response.statusCode() != 200) {
        throw new Exception("Request failed with status: " + response.statusCode());
    }

    return response.body();
}

// Usage
String accounts = getAccounts(token);
System.out.println("Accounts: " + accounts);

Ruby

# Step 2: Use the JWT token in subsequent requests
def get_accounts(token)
  uri = URI("#{BASE_URL}/accounts")
  
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Bearer #{token}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  unless response.is_a?(Net::HTTPSuccess)
    raise "Request failed with status: #{response.code}"
  end

  JSON.parse(response.body)
rescue StandardError => e
  puts "Request error: #{e.message}"
  raise
end

# Usage
accounts = get_accounts(token)
puts "Accounts: #{accounts}"

See also: POST /auth/login | POST /auth/logout

---

API Key Authentication

API keys are ideal for server-to-server integrations and persistent access without user interaction. API keys do not expire unless revoked.

Steps

1. Authenticate with a JWT token first (required to create API keys)
2. Call POST /auth/api-key with your JWT bearer token
3. Save the returned API key immediately - it's only shown once!
4. Use the API key in Authorization: Bearer <api-key> header for all future requests

Example: Create an API Key

cURL

# Step 1: Create an API key (requires JWT token)
JWT_TOKEN="<your-jwt-token>"

curl -X POST $BASE_URL/auth/api-key \
  -H "Authorization: Bearer $JWT_TOKEN"

# Response:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "apiKey": "magfi_YOUR_API_KEY_HERE"
# }
#
# ⚠️ IMPORTANT: Save this API key now - it will not be shown again!

JavaScript

// Step 1: Create an API key (requires JWT token)
async function createApiKey(jwtToken) {
  try {
    const response = await fetch(`${BASE_URL}/auth/api-key`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to create API key: ${response.status}`);
    }

    const data = await response.json();
    // ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
    console.log('API Key ID:', data.id);
    console.log('API Key:', data.apiKey);
    return data.apiKey;
  } catch (error) {
    console.error('Error creating API key:', error);
    throw error;
  }
}

// Usage
const apiKey = await createApiKey(jwtToken);
// Store apiKey in secure environment variable

Python

# Step 1: Create an API key (requires JWT token)
def create_api_key(jwt_token):
    try:
        response = requests.post(
            f"{BASE_URL}/auth/api-key",
            headers={"Authorization": f"Bearer {jwt_token}"}
        )
        response.raise_for_status()
        data = response.json()
        
        # ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
        print(f"API Key ID: {data['id']}")
        print(f"API Key: {data['apiKey']}")
        return data['apiKey']
    except requests.exceptions.RequestException as e:
        print(f"Error creating API key: {e}")
        raise

# Usage
api_key = create_api_key(jwt_token)
# Store api_key in secure environment variable

Go

type ApiKeyResponse struct {
    ID     string `json:"id"`
    ApiKey string `json:"apiKey"`
}

// Step 1: Create an API key (requires JWT token)
func createApiKey(jwtToken string) (string, error) {
    req, err := http.NewRequest("POST", BASE_URL+"/auth/api-key", nil)
    if err != nil {
        return "", fmt.Errorf("error creating request: %w", err)
    }

    req.Header.Set("Authorization", "Bearer "+jwtToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusCreated {
        return "", fmt.Errorf("failed to create API key with status: %d", resp.StatusCode)
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return "", fmt.Errorf("error reading response: %w", err)
    }

    var apiKeyResp ApiKeyResponse
    if err := json.Unmarshal(body, &apiKeyResp); err != nil {
        return "", fmt.Errorf("error parsing response: %w", err)
    }

    // ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
    fmt.Printf("API Key ID: %s\n", apiKeyResp.ID)
    fmt.Printf("API Key: %s\n", apiKeyResp.ApiKey)
    return apiKeyResp.ApiKey, nil
}

// Usage
apiKey, err := createApiKey(jwtToken)
if err != nil {
    fmt.Printf("Error creating API key: %v\n", err)
    return
}
// Store apiKey in secure environment variable

Rust

#[derive(Deserialize)]
struct ApiKeyResponse {
    id: String,
    #[serde(rename = "apiKey")]
    api_key: String,
}

// Step 1: Create an API key (requires JWT token)
async fn create_api_key(jwt_token: &str) -> Result<String, Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();

    let response = client
        .post(&format!("{}/auth/api-key", BASE_URL))
        .header("Authorization", format!("Bearer {}", jwt_token))
        .send()
        .await?;

    if !response.status().is_success() {
        return Err(format!("Failed to create API key with status: {}", response.status()).into());
    }

    let api_key_resp: ApiKeyResponse = response.json().await?;

    // ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
    println!("API Key ID: {}", api_key_resp.id);
    println!("API Key: {}", api_key_resp.api_key);
    Ok(api_key_resp.api_key)
}

// Usage
match create_api_key(&jwt_token).await {
    Ok(api_key) => {
        // Store api_key in secure environment variable
    },
    Err(e) => eprintln!("Error creating API key: {}", e),
}

Java

static class ApiKeyResponse {
    String id;
    String apiKey;
}

// Step 1: Create an API key (requires JWT token)
public static String createApiKey(String jwtToken) throws Exception {
    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(BASE_URL + "/auth/api-key"))
        .header("Authorization", "Bearer " + jwtToken)
        .POST(HttpRequest.BodyPublishers.noBody())
        .build();

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

    if (response.statusCode() != 201) {
        throw new Exception("Failed to create API key with status: " + response.statusCode());
    }

    ApiKeyResponse apiKeyResp = gson.fromJson(response.body(), ApiKeyResponse.class);

    // ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
    System.out.println("API Key ID: " + apiKeyResp.id);
    System.out.println("API Key: " + apiKeyResp.apiKey);
    return apiKeyResp.apiKey;
}

// Usage
String apiKey = createApiKey(jwtToken);
// Store apiKey in secure environment variable

Ruby

# Step 1: Create an API key (requires JWT token)
def create_api_key(jwt_token)
  uri = URI("#{BASE_URL}/auth/api-key")
  
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{jwt_token}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  unless response.code == '201'
    raise "Failed to create API key with status: #{response.code}"
  end

  data = JSON.parse(response.body)

  # ⚠️ IMPORTANT: Save this API key now - it will not be shown again!
  puts "API Key ID: #{data['id']}"
  puts "API Key: #{data['apiKey']}"
  data['apiKey']
rescue StandardError => e
  puts "Error creating API key: #{e.message}"
  raise
end

# Usage
api_key = create_api_key(jwt_token)
# Store api_key in secure environment variable

Example: Using the API Key

cURL

# Step 2: Use the API key in subsequent requests
API_KEY="magfi_YOUR_API_KEY_HERE"

curl -X GET $BASE_URL/accounts \
  -H "Authorization: Bearer $API_KEY"

JavaScript

// Step 2: Use the API key in subsequent requests
const API_KEY = process.env.MAGFI_API_KEY || "magfi_YOUR_API_KEY_HERE";

async function getAccounts() {
  try {
    const response = await fetch(`${BASE_URL}/accounts`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
      },
    });

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

    const accounts = await response.json();
    return accounts;
  } catch (error) {
    console.error('Request error:', error);
    throw error;
  }
}

Python

import os

# Step 2: Use the API key in subsequent requests
API_KEY = os.getenv('MAGFI_API_KEY', 'magfi_YOUR_API_KEY_HERE')

def get_accounts():
    try:
        response = requests.get(
            f"{BASE_URL}/accounts",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        raise

Go

import "os"

// Step 2: Use the API key in subsequent requests
func getAccountsWithApiKey() ([]byte, error) {
    apiKey := os.Getenv("MAGFI_API_KEY")
    if apiKey == "" {
        apiKey = "magfi_YOUR_API_KEY_HERE"
    }

    req, err := http.NewRequest("GET", BASE_URL+"/accounts", nil)
    if err != nil {
        return nil, fmt.Errorf("error creating request: %w", err)
    }

    req.Header.Set("Authorization", "Bearer "+apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("request failed with status: %d", resp.StatusCode)
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("error reading response: %w", err)
    }

    return body, nil
}

Rust

use std::env;

// Step 2: Use the API key in subsequent requests
async fn get_accounts_with_api_key() -> Result<String, Box<dyn std::error::Error>> {
    let api_key = env::var("MAGFI_API_KEY")
        .unwrap_or_else(|_| "magfi_YOUR_API_KEY_HERE".to_string());

    let client = reqwest::Client::new();

    let response = client
        .get(&format!("{}/accounts", BASE_URL))
        .header("Authorization", format!("Bearer {}", api_key))
        .send()
        .await?;

    if !response.status().is_success() {
        return Err(format!("Request failed with status: {}", response.status()).into());
    }

    let body = response.text().await?;
    Ok(body)
}

Java

// Step 2: Use the API key in subsequent requests
public static String getAccountsWithApiKey() throws Exception {
    String apiKey = System.getenv("MAGFI_API_KEY");
    if (apiKey == null) {
        apiKey = "magfi_YOUR_API_KEY_HERE";
    }

    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(BASE_URL + "/accounts"))
        .header("Authorization", "Bearer " + apiKey)
        .GET()
        .build();

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

    if (response.statusCode() != 200) {
        throw new Exception("Request failed with status: " + response.statusCode());
    }

    return response.body();
}

Ruby

# Step 2: Use the API key in subsequent requests
API_KEY = ENV['MAGFI_API_KEY'] || 'magfi_YOUR_API_KEY_HERE'

def get_accounts
  uri = URI("#{BASE_URL}/accounts")
  
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Bearer #{API_KEY}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  unless response.is_a?(Net::HTTPSuccess)
    raise "Request failed with status: #{response.code}"
  end

  JSON.parse(response.body)
rescue StandardError => e
  puts "Request error: #{e.message}"
  raise
end

Managing API Keys

List all your API keys: GET /auth/api-key

Delete an API key: DELETE /auth/api-key/:id

See also: POST /auth/api-key

---

Troubleshooting

Issue	Cause	Solution
401 Unauthorized	Missing or invalid token	Verify token is included in Authorization: Bearer <token> header
401 Unauthorized	Expired JWT token	JWT tokens expire after 1 hour. Request a new token via /auth/login
401 Unauthorized	Invalid credentials	Check email/password are correct
403 Forbidden	Valid token, insufficient permissions	Your account doesn't have access to this resource
403 with error code 1010	Missing User-Agent header	Include a User-Agent header in your requests (e.g., User-Agent: MyApp/1.0). Some HTTP clients (like Node.js fetch) don't send a User-Agent by default, which triggers Cloudflare's bot protection
API key not working	Key was deleted or never saved	API keys are shown only once. If lost, create a new one
Network errors	Connection issues or invalid BASE_URL	Verify you're using the correct environment URL (production or sandbox)

---

Security Reminders

• 🔒 Store API keys securely - Never commit them to version control. Use environment variables.
• 🔒 Use HTTPS only - The API enforces HTTPS, but ensure your client does too.
• 🔒 Rotate keys regularly - Delete old API keys you're no longer using via DELETE /auth/api-key/:id.