Getting Started¶

An Apilane Instance consists of two services (Portal + API) and can be deployed in any environment.

1. Start the Services¶

Execute the provided docker-compose.yaml to spin up both services. The Portal and the API share an installation key: the first command generates one into a .env file next to the compose file, only if it is not there yet. Keep that file for every later run.

grep -qs "^APILANE_INSTALLATION_KEY=." .env || echo "APILANE_INSTALLATION_KEY=$(openssl rand -hex 32)" >> .env
docker-compose -p apilane up -d

Without a POSIX shell (for example on Windows), create the .env file by hand: one line, APILANE_INSTALLATION_KEY= followed by a random value of 30 to 100 characters without spaces.

This starts:

• Portal on http://localhost:5000 — management UI (and the management API it is built on, under /api/v1)
• API on http://localhost:5001 — REST API for client applications

2. Log in to the Portal¶

Open http://localhost:5000. The first screen requires administrator setup:

1. Choose the email address you want to use for the administrator account.
2. Enter the random temporary password printed in the Portal startup output. For Compose, read it with docker-compose -p apilane logs apilanewebportal.
3. Choose and confirm a new password. All other Portal operations remain blocked until this succeeds.

Existing installations without a bootstrap record are marked as already set up. Their accounts and passwords are left unchanged.

3. Create Your First Application¶

1. In the Portal, open Applications and click New application
2. Enter a name (e.g., MyApp)
3. Select a Server (the API service)
4. Choose a Database type (SQLite is recommended for getting started)
5. Click Save

Your application is now ready and its Entities tab opens. Note the Application Token — you'll need it for API calls. The Info button of the application shows it.

4. Define an Entity¶

1. Open your application in the Portal
2. On the Entities tab click New entity
3. Name it Products
4. Open the entity and add its properties with New property:
   • Name (String, Required)
   • Price (Number)
   • InStock (Boolean)

5. Allow Access to the Entity¶

A new entity is private: the API refuses every call that no access rule allows, so the calls below would answer UNAUTHORIZED. Add a rule for this walkthrough:

1. Open the Security tab of the application
2. Under Access rules, pick Products in the list of items
3. In the Anonymous row switch on GET, POST, PUT and DELETE
4. For GET, POST and PUT click Select all under Properties (a rule without properties returns only the ID on GET and refuses POST and PUT)
5. Click Save

6. Make Your First API Call¶

With the entity and its access rule in place, you can start making API calls. Replace {appToken} with your Application Token.

Create a record:

curl -X POST "http://localhost:5001/api/Data/Post?entity=Products" \
  -H "x-application-token: {appToken}" \
  -H "Content-Type: application/json" \
  -d '{"Name": "Widget", "Price": 9.99, "InStock": true}'

Response: [1] — an array containing the new record's ID.

Read records:

curl "http://localhost:5001/api/Data/Get?entity=Products" \
  -H "x-application-token: {appToken}"

Response:

{
  "Data": [
    { "ID": 1, "Name": "Widget", "Price": 9.99, "InStock": true, "Owner": null, "Created": 1704067200000 }
  ]
}

Update a record:

curl -X PUT "http://localhost:5001/api/Data/Put?entity=Products" \
  -H "x-application-token: {appToken}" \
  -H "Content-Type: application/json" \
  -d '{"ID": 1, "Price": 12.99}'

Delete a record:

curl -X DELETE "http://localhost:5001/api/Data/Delete?entity=Products&ids=1" \
  -H "x-application-token: {appToken}"

7. Register a User¶

To use authenticated endpoints, first make sure Allow new users to register is on (the Security tab of the application in the Portal), then:

curl -X POST "http://localhost:5001/api/Account/Register" \
  -H "x-application-token: {appToken}" \
  -H "Content-Type: application/json" \
  -d '{"Email": "[email protected]", "Username": "john", "Password": "SecurePass123!"}'

Login and get an auth token:

curl -X POST "http://localhost:5001/api/Account/Login" \
  -H "x-application-token: {appToken}" \
  -H "Content-Type: application/json" \
  -d '{"Email": "[email protected]", "Password": "SecurePass123!"}'

Response:

{
  "AuthToken": "a1b2c3d4-...",
  "User": { "ID": 1, "Email": "[email protected]", "Username": "john", ... }
}

Use the AuthToken in subsequent requests via the Authorization header. This call works with the Anonymous rule of step 5, because a signed-in user also gets what Anonymous has:

curl "http://localhost:5001/api/Data/Get?entity=Products" \
  -H "x-application-token: {appToken}" \
  -H "Authorization: Bearer a1b2c3d4-..."

Environment Variables¶

Regardless of deployment method (Docker, k8s, cloud), you can override default settings via environment variables, using __ for nesting (for example OpenTelemetry__Tracing__Enabled).

The "Compose file" column shows the values of docker-compose.yaml. A setting that is not set there takes the development default of the appsettings.json inside the image (http://localhost:5000 and http://localhost:5001, and a Windows FilesPath), so in a container always set Url to http://0.0.0.0:{port} and FilesPath to a mounted volume.

Portal¶

API¶

Both services¶