Overview

The Pelcro Core API is a set of programming tools that allows you to directly integrate your own systems and applications with Pelcro's platform. Our RESTful API is easy to understand with predictable URLs and standard HTTP methods for actions and error handling. You can securely interact with the API from your web applications, and it uses JSON for all data communication.

Use-cases

• Automated Tasks: Streamline your business processes by automating actions within Pelcro based on events or triggers in your external systems.
• Customized Features: Build tailored functions and experiences beyond what's natively available in the Pelcro Dashboard.
• Data Integration: Seamlessly sync data between Pelcro and your existing software tools like a CRM, accounting software, or other databases.
• Advanced Reporting & Analytics: Pull raw data for custom reporting or integration with your own business intelligence tools.

Identification

In order to use Core API endpoints, your account needs to be identified, which is done via your Site ID. This identifier is not meant to be a secret. It is similar to a publishable key and is directly linked to your account. Therefore, the site_id is required at all times, either as a query parameter or as part of the body of the requests, depending on the endpoint.

You can retrieve your Site ID either from your Pelcro site settings, or in the browser URL of your Pelcro platform (e.g., https://pelcro.com/admin/{site_id}/customers).

Authentication

In addition to the site_id to identify your account, all requests needs to be authenticated. This is achieved by sending your API key as a Bearer token using the HTTP Authorization request header:

Host: www.pelcro.com
User-Agent: curl/8.7.1
Content-Type: application/json
Authorization: Bearer eyJ0eXA... <-- Your API key here

To create and manage API keys, head to the API keys management section in the platform, under your account settings. Note that only account owners & collaborators of type administrators can create and manage API keys.

Treat your API key as a confidential and sensitive password, Pelcro will never ask your for this information. Avoid sharing it with your colleagues, and do not share it publicly (e.g., in documentation, client-side code or in a repository in GitHub).

API authentication methods

OAuth 2.0

Use the industry standard OAuth 2.0 to authenticate requests to our Core API.

Authorization request:

GET https://pelcro.com/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &response_mode=query

After the user authorizes, they will be redirected to your redirect URI with the authorization code: https://yourRedirectUrl.com?code={code}

Token request:

POST https://pelcro.com/oauth/token

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "code": "YOUR_AUTHORIZATION_CODE"
}

Token response:

{
  "token_type": "Bearer",
  "expires_in": 172800,
  "access_token": "ACCESS_TOKEN"
}

Note: The access token is valid for 2 days and is scoped to the account where the application credentials were created.

API keys management

API keys do not expire. It is your responsibility to keep your keys secure and rotate them periodically as a security best practice.

Statuses

API keys can have one of the following statuses:

Revoking keys

You can revoke active API key access by choosing "Revoke" from the action menu next to the corresponding API key. When the API key is revoked, it can no longer grant access to Core API functionality, and any requests using it will fail.

Revoked API keys continue to remain on your API key list. If an API key is revoked manually, the revocation date will be shown on the informational tooltip next to the status tag for the corresponding API key.

Reactivating keys

You can reactivate revoked API key access by choosing "Reactivate" from the action menu next to the corresponding API key. When the API key is reactivated, access will be restored to Core API functionality.

Deleting keys

You can delete revoked API keys by choosing "Delete" from the action menu next to the corresponding API key. When the API key is deleted, it will disappear from the list and cannot be reinstated.

Security best practices

Since API keys do not expire, proper key management is critical:

• Use environment variables: Store your API key in environment variables (e.g., .env files) rather than hardcoding it in your source code.
• Inject at build/deploy time: For production systems, inject API keys at the infrastructure level during deployment rather than storing them in configuration files.
• Never log API keys: Ensure your logging and monitoring systems do not capture or store API keys in logs, traces, or error reports.
• Never commit to version control: Add .env and any files containing API keys to your .gitignore to prevent accidental commits.
• Restrict access: Limit who in your organization has access to API keys. Only account owners and administrators should manage them.
• Rotate keys periodically: Even though keys don't expire, establish a regular rotation schedule (e.g., quarterly) to minimize risk from potential exposure.
• Revoke immediately if compromised: If you suspect a key has been exposed, revoke it immediately and generate a new one.