> For the complete documentation index, see [llms.txt](https://docs.blitzware.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blitzware.xyz/getting-started/basic-application.md).

# Quickstart: Basic Application

Create a Basic Application and complete direct API-driven login.

A Basic Application is the fastest way to add username/password authentication when your product calls BlitzWare directly over HTTP. Use it for desktop clients, API-driven apps, license-aware products, and lightweight integrations that do not need redirect-based OAuth flows.

For the platform choice behind this guide, read [Choosing Between OAuth and Basic Applications](/core-platform/choosing-between-oauth-and-basic.md).

## Before you start

You need a BlitzWare account, access to the dashboard, and a production or staging backend that can keep an API Key secret.

{% hint style="warning" %}
Do not embed broad or long-lived API Keys in public browser code. For browser apps, prefer an OAuth Application or proxy Basic API calls through your backend.
{% endhint %}

## 1. Create the Application

In the dashboard, create a **Basic Application** for the product environment you are integrating. Keep staging and production as separate Applications so API Keys, Users, logs, and security settings do not mix.

Configure the minimum production settings:

| Setting         | Recommended starting point                                     |
| --------------- | -------------------------------------------------------------- |
| `freeMode`      | Enable only if your app does not require licenses.             |
| `twoFactorAuth` | Enable for sensitive products.                                 |
| `hwidCheck`     | Enable only when device binding is part of your product model. |
| `developerMode` | Disable in production.                                         |

## 2. Create a scoped API Key

Create an API Key for this Application with only the scopes your integration needs.

For a first username/password flow, use:

```
applications:initialize
users:register
users:login
users:passwordReset
```

Learn how scopes work in [API Keys](/applications/api-keys.md) and [Scopes and Permissions](/applications/scopes-and-permissions.md).

## 3. Initialize your client

Call initialization when your app starts so it can retrieve the Application status and security policy.

```http
POST https://api.blitzware.xyz/api/applications/initialize
Content-Type: application/json
x-api-key: bwk_xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Handle `401` as a key/configuration problem and `429` as a retry/backoff problem. See [Error Handling](/developers/error-handling.md).

## 4. Register and login a User

Registration and login are Basic Application workflows. The protocol reference remains in the [Basic Universal API](https://docs.blitzware.xyz/basic/).

```http
POST https://api.blitzware.xyz/api/users/login
Content-Type: application/json
x-api-key: bwk_xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```json
{
  "username": "sarah.admin",
  "password": "correct-horse-battery-staple",
  "twoFactorCode": "",
  "hwid": "device-9b2d54",
  "lastIP": "203.0.113.42",
  "applicationId": "00000000-0000-0000-0000-000000000000"
}
```

## 5. Store the returned Token safely

The returned Token represents an authenticated Basic Application User. Store it according to the client type:

| Client                     | Recommended storage                                           |
| -------------------------- | ------------------------------------------------------------- |
| Server-rendered web app    | HttpOnly, Secure, SameSite cookie controlled by your backend. |
| Desktop or mobile app      | OS-backed secure storage.                                     |
| CLI or service integration | Encrypted local secret store or runtime secret manager.       |

Review [Sessions and Tokens](/core-platform/sessions-and-tokens.md) before production.

## Next steps

* Configure the [Hosted User Store](/identity/hosted-user-store.md) or [Database Connections](/identity/database-connections.md).
* Add [MFA and Account Protection](/core-platform/mfa-and-account-protection.md).
* Review the [Production Deployment Checklist](/developers/production-deployment-checklist.md).