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:
On MARCO Console, go to Marpps > Register Application:
Set a name for the application. For example,
My first Marpp
.Click Register Application.
Copy and save the Application ID and Application Token:
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:
On MARCO Console, go to Service Accounts > Register Account:
Set a name for the account.
Click Register Service Account.
dangerIt'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.
Copy and save the service account Email:
Open the Service Account API Keys tab.
Click Generate API Key.
Copy and save the service account API Token:
3. Grant permissions to the service account
To let the service account act on behalf of the application, follow the next steps:
On MARCO Console, go to Service Accounts > List service accounts:
Select your service account.
Go to the Service Account Marpp Access Control tab.
In the Select Marpp field, choose your target marpp.
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:
In the command line, run the following command, replacing
APPLICATION_ID
,SERVICE_ACCOUNT_EMAIL
andSERVICE_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>Copy and save the
access_token
value from the response:{
"access_token": "eyJra...w4lqw",
"token_type": "Bearer",
"expires_in": 299
}cautionThe 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.