> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincode.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get your integration up and running in under 15 minutes.

Get started with FinCode's multitenant platform in three simple steps. This guide will walk you through account setup, authentication, and making your first API call.

## Step 1: Account Setup & Due Diligence

<AccordionGroup>
  <Accordion icon="clipboard-check" title="Complete Due Diligence">
    Before you can start integrating, you will need to complete our general onboarding process with the following steps:

    1. **Submit Application**: Visit [fincode.co.uk/contact-us](https://fincode.co.uk/contact-us) to begin your application.
    2. **Provide Documentation**: Submit required business documents.
    3. **KYC/KYB Verification**: Complete the different verification processes.
    4. **Compliance Review**: Our team will review your application (typically 2-3 days).
    5. **Account Approval**: Receive approval notification with your sandbox details.

    <Tip>Have your business registration documents, proof of address, and compliance certificates ready to speed up the process.</Tip>
  </Accordion>

  <Accordion icon="server" title="Get Your Credentials">
    Once approved, you'll receive your unique sandbox credentials:

    ### Your Domain Format

    ```
    https://{domain}.fincode.software
    ```

    Your domain is your dedicated environment where all your API calls will be made. This ensures complete tenant isolation and data security.

    <Info>Your domain will be provided in your approval email. Keep this information secure as it's required for all API requests.</Info>
  </Accordion>

  <Accordion icon="box" title="Access Your Sandbox">
    After approval, you'll have access to two environments:

    * **Sandbox**: `https://{domain}.fincode.software/sandbox`
    * **Production**: `https://{domain}.fincode.tech`

    Log in to your dashboard at your domain to access:

    * API documentation specific to your tenant
    * Sandbox test data and accounts
    * Configuration settings
    * Webhook management
    * Analytics and reporting

    <Warning>Always test thoroughly in sandbox before moving to production.</Warning>
  </Accordion>
</AccordionGroup>

## Step 2: Generate API Tokens

<AccordionGroup>
  <Accordion icon="key" title="Two ways to generate a token">
    1. Populate Login Details and login through the API
    2. Generate a token for selected environment or service on your dashboard
  </Accordion>

  <Accordion icon="shield" title="Token Security Best Practices">
    ### Protecting Your Tokens

    * Never commit tokens to version control
    * Use environment variables for token storage
    * Rotate tokens every 90 days or when compromised
    * Use least-privilege principle - only grant necessary permissions
    * Monitor token usage in your dashboard

    ### Environment Variables Setup

    ```bash theme={null}
    # Add to your .env file
    DOMAIN=domain
    JWT_ACCESS_TOKEN=fct_sandbox_your_token_here
    FINCODE_BASE_URL=https://{domain}.fincode.software
    ```

    <Warning>If you suspect a token has been compromised, revoke it immediately from your dashboard.</Warning>
  </Accordion>
</AccordionGroup>

## Step 3: Make Your First API Call

Test your authentication by logging in via API. This will verify your setup and return an access token for subsequent requests.

<AccordionGroup>
  <Accordion icon="code" title="Node.js Example">
    ```javascript theme={null}
    const axios = require('axios');

    const DOMAIN = process.env.DOMAIN;
    const JWT_ACCESS_TOKEN = process.env.JWT_ACCESS_TOKEN;
    const BASE_URL = `https://${DOMAIN}.fincode.software`;

    async function login() {
      try {
        const response = await axios.put(
          `${BASE_URL}/api/v6/services/securitymanagement/login`,
          {
            email: 'your-email@company.com',
            currentPassword: 'your-password'
          },
          {
            headers: {
              'Content-Type': 'application/json',
              'uuid': 200,
              'platform': 'fincode'
            }
          }
        );

        console.log('Login successful!');
        console.log('Access Token:', response.data.token);

        return response.data;
      } catch (error) {
        console.error('Login failed:', error.response?.data || error.message);
        throw error;
      }
    }

    login()
      .then(data => {
        const accessToken = data.access_token;
        console.log('Ready to make API calls!');
      })
      .catch(err => {
        console.error('Authentication error:', err);
      });
    ```

    **Expected Response:**

    ```json theme={null}
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "modules": ["REMITTANCE", "LENDING"],
      "country": "Nigeria",
      "expires_in": 3600,
      "organisation": "def50200a1b2c3d4e5f6...",
      "profileDetailsResponseDTO": {
        "phone": "448182147656",
        "dob": "1994-02-24",
        "email": "your-email@company.com",
        "userType": "REGISTERED_CUSTOMER",
        "id": "8ecca811-607f-44e1-a57e-cd856c50437d",
        "accessScope": "CUSTOMER_FLOW",
      }
    }
    ```
  </Accordion>

  <Accordion icon="code" title="Java Example">
    ```java theme={null}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.http.HttpRequest.BodyPublishers;
    import com.google.gson.Gson;
    import com.google.gson.JsonObject;

    public class FinCodeAuth {
        private static final String DOMAIN = System.getenv("DOMAIN");
        private static final String JWT_ACCESS_TOKEN = System.getenv("JWT_ACCESS_TOKEN");
        private static final String BASE_URL = String.format(
            "https://%s.fincode.software",
            DOMAIN
        );

        public static class LoginResponse {
            public String token;
            public String role;
            public int currencyCode;
            public String twoFactorEnabled;
            public String organisation;
            public ProfileDetailsResponseDTO user;

            public static class User {
                public String id;
                public String firstName;
                public String lastName;
                public String phone;
            }
        }

        public static LoginResponse login(String email, String currentPassword) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            Gson gson = new Gson();

            JsonObject requestBody = new JsonObject();
            requestBody.addProperty("email", email);
            requestBody.addProperty("currentPassword", currentPassword);

            // Build request
                .uri(URI.create(BASE_URL + "/api/v6/services/securitymanagement/login"))
                .header("Content-Type", "application/json")
                .header("uuid", "200")
                .header("platform", "fincode")
                .PUT(BodyPublishers.ofString(gson.toJson(requestBody)))
                .build();

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

            if (response.statusCode() == 200) {
                System.out.println("Login successful!");
                LoginResponse loginResponse = gson.fromJson(
                    response.body(),
                    LoginResponse.class
                );

                System.out.println("Access Token: " + loginResponse.token);

                return loginResponse;
            } else {
                throw new Exception("Login failed: " + response.body());
            }
        }

        public static void main(String[] args) {
            try {
                LoginResponse response = login(
                    "your-email@company.com",
                    "your-password"
                );

                String accessToken = response.token;
                System.out.println("Ready to make API calls!");

            } catch (Exception e) {
                System.err.println("Authentication error: " + e.getMessage());
                e.printStackTrace();
            }
        }
    }
    ```
  </Accordion>

  <Accordion icon="terminal" title="cURL Example">
    ```bash theme={null}
    curl -X PUT "https://{domain}.fincode.software/api/v6/services/securitymanagement/login" \
      -H "Content-Type: application/json" \
      -H "uuid: 200" \
      -H "platform: fincode" \
      -d '{
        "email": "your-email@company.com",
        "currentPassword": "your-password"
      }'
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you're authenticated, choose your product to continue:

<CardGroup cols={3}>
  <Card title="Remittance" icon="money-bill-transfer" href="/remittance/overview">
    * Create beneficiary
    * Get FX quote
    * Send transaction
  </Card>

  <Card title="Digital Lending" icon="hand-holding-dollar" href="/lending/overview">
    * Create customer
    * Submit application
    * Check decision
  </Card>

  <Card title="Investment" icon="chart-line" href="/investment/overview">
    * Create account
    * Add portfolio
    * Execute trades
  </Card>
</CardGroup>

***

## Common Issues & Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="Authentication Errors">
    **401 Unauthorized**

    * Verify your API token is correct and not expired
    * Ensure you're using the correct domain
    * Check that your token has the necessary permissions

    **403 Forbidden**

    * Your account may not have access to the requested resource
    * Contact support to verify your tenant permissions
  </Accordion>

  <Accordion icon="clock" title="Token Expiration">
    Access tokens expire after 1 hour. Use the refresh token to get a new access token:

    ```javascript theme={null}
    const response = await axios.post(
      `${BASE_URL}/api/v6/services/securitymanagement/refresh`,
      {
        refresh_token: refreshToken
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Token': JWT_ACCESS_TOKEN
        }
      }
    );
    ```
  </Accordion>

  <Accordion icon="life-ring" title="Need Help?">
    * **Documentation**: Browse our [API Reference](/api/authentication)
    * **Support**: Email [hello@fincode.co.uk](mailto:hello@fincode.co.uk)
    * **System Status**: Check [status.fincode.com](https://status.fincode.com)
    * **Community**: Visit our [GitHub](https://github.com/fincodeuk) for examples
  </Accordion>
</AccordionGroup>