Decoo provides HTTP API to facilitate Decoo service usage. Under the One Cloud, Multiple Endpoints architecture, both Decoo Cloud and Endpoint are deployed with HTTP API to provide different types of services, with different authentication mechanisms.
- Decoo Cloud provides all APIs except for file upload APIs like pinFile and pinByHash, using API Key for authentication.
- Endpoint provides file upload APIs like pinFile and pinByHash, using OAuth2-like mechanisms for access authorization and authentication.
API Keys are used to access Decoo Cloud API. When registering an account, an API Key is automatically generated. User could login in and check their API Key at panel -> API -> API JWT.
Each API Key is actually a JWT token which acts on behalf of the user when accessing Decoo API. Users should keep it private and never share it with others.
The base url of Decoo Cloud API is: https://api.decoo.io
To authenticate with this endpoint, you need to include your API Key as an Authorization header for all your API requests in the following format:
You can use following curl request to test your API Key against the endpoint:
On success, it should return with 200 and the following body:
If token is invalid, it should return following body:
Client could request Decoo Cloud API to get Endpoint list:
It should return results like below:
Endpoint use Access Token to authenticate user's API requests. Access Tokens are issued and verified by Decoo Cloud. The process flow is:
- Client requests Access Token via Decoo Cloud API
- Client calls Endpoint API, with the requested Access Token in request header
- Endpoint calls Decoo Cloud API to verify the passed Access Token. If the token is valid, authenticate passes; otherwise, authenticate fails and 401 error will be returned to Client.
Besides, Access Token expires in 2 hours. Client should request a new Access Token if old ones expire.
To request Access Token：
When calling Endpoint's pinFile or pinByHash API, user need attach a digital signature as API calling proof. The digital signature is generated by encrypting file CID with user's RSA private key, and will be verified by Decoo Cloud using user's RSA public key.
RSA Keys are automatically generated when registering accounts. User could login and check it at panel -> API -> Verification Key.
There are mutltiple approaches to get a file's IPFS CID. Normally, the suggested way is to install IPFS Desktop locally, and using its /api/v0/add HTTP API to get a local file's CID (Note: When calling this API, it's suggested to set only-hash parameter value as true).
For other commonly used programming languages, sample codes are like below:
User must have a valid Access Token to access Endpoint API. Besides, to access file upload APIs like pinFile and pinByHash, a digital signature based on user RSA private key and file CID is also required.
As an example, user could use curl command below to access a Endpoint's pinFile API:
The SDK could be used in both NodeJS and Browser environment. Please refer to the SDK for detailed usage.