Skip to main content

Quickstart

Welcome to MARCO docs! This guide provides step-by-step instructions on creating your first distributed app and obtaining tokens to interact with our APIs.

Prerequisites​

Before diving in, ensure you have a MARCO account:

  • If your organization is already on MARCO, you can get an invitation through Send invitations.

  • If your organization is not on MARCO, you can request a demo account through our Contact page. Our team will contact you to discuss your needs and initiate the account creation process.

Once you receive the invitation, follow the registration link provided in the email from MARCO to complete the registration process.

1. Create an application​

The first step involves registering a distributed application, also known Marpps, within MARCO.

To create a Marpps:

  1. On MARCO Console, go to Marpps > Register Application:

    Marpp registration

  2. Set a name for the application. For example, My first Marpp.

  3. Click Register Application.

  4. Copy and save the Application ID and Application Token:

    Marpp registration

You will use the application ID and token to reference your application in API requests.

2. Create a service account​

Next, you need to register a service account, which authenticates your computer as an authorized user for API requests.

To create a service account:

  1. On MARCO Console, go to Service Accounts > Register Account:

    Service account registration

  2. Set a name for the account.

  3. Click Register Service Account.

    danger

    It's crucial to keep service account credentials secret. Sharing these credentials can compromise the account and associated resources. If you suspect that a service account has been compromised, you can disable it and create a new one in the Service Accounts section of the MARCO Console.

  4. Copy and save the service account Email:

    Service account email

  5. Open the Service Account API Keys tab.

  6. Click Generate API Key.

  7. Copy and save the service account API Token:

    Service account token

3. Grant permissions to the service account​

To let the service account act on behalf of the application, follow the next steps:

  1. On MARCO Console, go to Service Accounts > List service accounts:

  2. Select your service account.

  3. Go to the Service Account Marpp Access Control tab.

    Marpp permissions

  4. In the Select Marpp field, choose your target marpp.

  5. Assign a role for the Marpp, such as FULL_ACCESS or a more restrictive option. For more information, see Privileges.

4. Create an access token​

Finally, you will generate an access token by combining your service account API key and application ID. This access token is required for most API calls and follows the bearer token authentication scheme.

To get an access token:

  1. In the command line, run the following command, replacing APPLICATION_ID,SERVICE_ACCOUNT_EMAIL and SERVICE_ACCOUNT_API_TOKEN with your credentials from the previous steps:

    curl -X POST "https://api-marco.finboot.com/v1/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=<APPLICATION_ID>" \
     -d "client_secret=<SERVICE_ACCOUNT_API_TOKEN>" \
     -d "grant_type=client_credentials" \
     -d "service_account=<SERVICE_ACCOUNT_EMAIL>

  2. Copy and save the access_token value from the response:

    {
        "access_token": "eyJra...w4lqw",
        "token_type": "Bearer",
        "expires_in": 299
    }
    caution

    The access token expires has a lifespan of 300 seconds (5 minutes) To maintain uninterrupted use of the API, ensure to generate a new access token each time the current one expires.

For more information on how to use the access token to authenticate API calls, see HTTP Requests.

Next steps​

Great work! You now have an application, a service account, and an access token, ready to interact with the MARCO API. To continue expanding your knowledge, consider exploring the following documentation:

  • Concepts: Gain a deeper understanding of MARCO's architecture and main features.
  • Guides: Learn how to use the MARCO Platform to build ledger agnostic applications.
  • Clients: Interact with MARCO API using your preferred programming language.
  • API Reference: Discover the REST APIs that allow you to integrate MARCO into your own applications and services.