---
updatedAt: 2026-06-18T01:37:18.000Z
agentTools:
  projectIndex: https://docs.pelcro.com/llms.txt
---

# Mobile App Integration

Integrate a mobile app with the Pelcro Open API — authenticate, store the JWT, and call protected endpoints.

The Pelcro Open API provides RESTful endpoints for mobile app integration. Use the authentication endpoints to obtain a customer **JWT**, then send that token in the `Authorization` header on protected requests.

**Base URL:** `https://www.pelcro.com/api/v1/sdk`
**Full reference:** [Open API](https://docs.pelcro.com/reference/api-open-intro)

```http
# Log in, then call a protected endpoint
POST /api/v1/sdk/auth/login?site_id={site_id}
Content-Type: application/json

{ "email": "user@example.com", "password": "password" }

# The response includes data.auth_token — store it securely, then:
POST /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer {auth_token}
```

***

## Prerequisites

| Requirement | Description                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| **Site ID** | Your Pelcro site identifier (from the dashboard), sent as `?site_id=` on every request. |
| **HTTPS**   | All API requests must use HTTPS.                                                        |
| **JSON**    | Send `Content-Type: application/json` with JSON bodies on `POST`/`PUT`.                 |

***

## Authentication flow

```
Mobile App → Register / Login → receive JWT (data.auth_token) → store securely → send as Authorization: Bearer on protected endpoints
```

***

## Authentication endpoints

| Endpoint                     | Method | Auth required | Description                                                       |
| ---------------------------- | ------ | ------------- | ----------------------------------------------------------------- |
| `/auth/register`             | POST   | No            | Register a new customer and receive an auth token.                |
| `/auth/login`                | POST   | No            | Log in an existing customer and receive an auth token.            |
| `/auth/logout`               | POST   | Yes           | Invalidate (blacklist) the current token.                         |
| `/auth/idp/login`            | POST   | No            | Social / identity-provider login (`google`, `facebook`, `auth0`). |
| `/auth/passwordless/request` | POST   | No            | Request a passwordless login token by email.                      |
| `/auth/passwordless/login`   | POST   | No            | Log in using a passwordless token.                                |

***

## Site & configuration

| Endpoint                     | Method     | Auth required | Description                                                                             |
| ---------------------------- | ---------- | ------------- | --------------------------------------------------------------------------------------- |
| `/site`                      | GET        | No            | Get the site configuration (the [Site resource](https://docs.pelcro.com/reference/api-open-resources#site-resource)). |
| `/plan`                      | GET / POST | No            | Retrieve a single plan by `plan_id`.                                                    |
| `/plan/ip/authorization`     | GET        | No            | Free plans whose authorized IP ranges include the requester's IP.                       |
| `/plan/domain/authorization` | GET        | No            | Free plans whose authorized domains match the requester's email domain.                 |
| `/geo/country`               | GET        | No            | Resolve the visitor's country by IP.                                                    |
| `/location`                  | GET        | No            | Resolve the visitor's location.                                                         |

***

## Authentication pattern

### Register a new customer

```http
POST /api/v1/sdk/auth/register?site_id={site_id}
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123",
  "first_name": "John",
  "last_name": "Doe"
}
```

| Field          | Type   | Required | Description                                                                |
| -------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `email`        | string | Yes      | The customer's email address (unique per account).                         |
| `password`     | string | Yes      | Minimum 6 characters (stricter if Strong Password Enforcement is enabled). |
| `first_name`   | string | No       | First name.                                                                |
| `last_name`    | string | No       | Last name.                                                                 |
| `display_name` | string | No       | Display name (max 100 characters).                                         |
| `username`     | string | No       | Unique username (alphanumeric / dashes / underscores, max 100).            |
| `phone`        | string | No       | Phone number.                                                              |
| `language`     | string | No       | Two-letter language code (e.g. `en`, `fr`).                                |
| `metadata`     | object | No       | Arbitrary key-value pairs.                                                 |

**Success response (`200`):** the shared [Customer resource](https://docs.pelcro.com/reference/api-open-resources#customer-resource), including `data.auth_token` and `data.token`.

```json
{
  "status": "success",
  "data": {
    "id": 1039,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "auth_token": "eyJ0xxx",
    "token": "eyJ0xxx",
    "subscriptions": null,
    "addresses": null
  }
}
```

### Log in an existing customer

```http
POST /api/v1/sdk/auth/login?site_id={site_id}
Content-Type: application/json

{ "email": "user@example.com", "password": "securePassword123" }
```

| Field      | Type   | Required | Description                                                      |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| `email`    | string | Yes\*    | The customer's email (\*required if `username` is not provided). |
| `username` | string | Yes\*    | Username (\*required if `email` is not provided).                |
| `password` | string | Yes      | The customer's password.                                         |

**Note:** provide either `email` **or** `username`. After repeated failed attempts the account is temporarily locked, returning **`400`** with a "Too many login attempts" validation message (default: 10 attempts / 5-minute window, configurable per account).

The success response is the same [Customer resource](https://docs.pelcro.com/reference/api-open-resources#customer-resource) shape as register, with the customer's `subscriptions`, `addresses`, etc. populated.

### Store the token securely

After register/login, persist `data.auth_token` in the platform's secure storage:

* **iOS:** Keychain Services
* **Android:** Keystore / `EncryptedSharedPreferences`

### Make authenticated requests

Send the token in the `Authorization` header on protected endpoints:

```http
PUT /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer {auth_token}
Content-Type: application/json

{ "first_name": "Jane", "last_name": "Smith" }
```

### Log out

```http
POST /api/v1/sdk/auth/logout?site_id={site_id}
Authorization: Bearer {auth_token}
```

Logout **blacklists** the token server-side (it can no longer be used) and returns the customer resource. Clear the token from device storage afterwards.

***

## Token management

| Property    | Value                                                                        |
| ----------- | ---------------------------------------------------------------------------- |
| **Type**    | JWT (JSON Web Token)                                                         |
| **TTL**     | 60 days by default; configurable per site via `auth_token_ttl_days` (1–365). |
| **Storage** | Secure device storage (Keychain / Keystore).                                 |
| **Header**  | `Authorization: Bearer {token}`                                              |

You can mint a fresh token without re-entering credentials via `POST /customer/refresh` (protected).

***

## Response & error formats

Successful responses return JSON under a `data` key — either `{"status":"success","data":{…}}` or `{"error":false,"data":…}` depending on the endpoint. The shape of each object is documented in [Resources](https://docs.pelcro.com/reference/api-open-resources).

Errors come back in one of two shapes (see [Errors](https://docs.pelcro.com/reference/api-open-errors) for the full reference):

* **Validation** (`400`) — `{"errors":{"field":["message"]}}`
* **Application / auth** — `{"error":{"report_id":null,"status":404,"message":"…"}}` (`report_id` is present on server errors)

### HTTP status codes

| Code  | Meaning           | Action                                                                        |
| ----- | ----------------- | ----------------------------------------------------------------------------- |
| `200` | Success           | Process the response.                                                         |
| `400` | Bad request       | Validation failed (`{"errors":{…}}`) or a business rule rejected the request. |
| `401` | Unauthorized      | No token was provided on a protected endpoint — prompt the user to log in.    |
| `403` | Forbidden         | The token is invalid, expired, or blacklisted — re-authenticate.              |
| `404` | Not found         | Missing resource, or a domain rejection (e.g. invalid credentials).           |
| `429` | Too many requests | Throttled (e.g. passwordless/email requests) — back off and retry.            |
| `500` | Server error      | Retry later or contact support with the `report_id`.                          |

### Error examples

**Validation (`400`):**

```json
{ "errors": { "email": ["The email has already been taken."] } }
```

**Invalid credentials (`404`):**

```json
{ "error": { "report_id": null, "status": 404, "message": "Invalid credentials! Please try again." } }
```

**Account locked (`400`):**

```json
{ "errors": { "email": ["Too many login attempts. Please try again later."] } }
```

**No token provided (`401`):**

```json
{ "error": { "message": "Token not provided" } }
```

**Invalid / expired token (`403`):**

```json
{ "error": { "status": 403, "message": "Authentication token has expired, please try again" } }
```

***

## Security best practices

1. **Store tokens in secure storage** — iOS Keychain, Android Keystore / `EncryptedSharedPreferences`.
2. **Never store tokens in plain text** — avoid `UserDefaults`, `SharedPreferences`, or plain files.
3. **Use HTTPS only** and validate SSL certificates.
4. **Handle expiry** — on `403`, clear the token and re-authenticate (or refresh proactively).
5. **Clear tokens on logout** — remove them from secure storage completely.
6. **Never log tokens.**
7. **Consider certificate pinning** for additional protection.

***

## Complete reference

This guide covers the most common endpoints for mobile integration. For the full list — subscriptions, memberships, payment methods, addresses, e-commerce, and invoices — see the [Open API reference](https://docs.pelcro.com/reference/api-open-intro).

***

## Quick-start checklist

| Step | Action                                                               |
| ---- | -------------------------------------------------------------------- |
| 1    | Get your `site_id` from the Pelcro dashboard.                        |
| 2    | Implement register / login to obtain the JWT (`data.auth_token`).    |
| 3    | Store the token in secure device storage (Keychain / Keystore).      |
| 4    | Send `Authorization: Bearer {token}` on protected requests.          |
| 5    | On `403`, re-authenticate (or refresh via `POST /customer/refresh`). |
| 6    | Call `POST /auth/logout` to blacklist the token server-side.         |
| 7    | Test the auth flow and error handling.                               |

***

## Additional resources

* [Open API overview](https://docs.pelcro.com/reference/api-open-intro)
* [Errors](https://docs.pelcro.com/reference/api-open-errors)
* [Resources](https://docs.pelcro.com/reference/api-open-resources)

For support, contact <support@pelcro.com>.