# Mobile Audit REST API Endpoints and Authentication Guide

> Access Mobile Audit REST API endpoints using token authentication. Learn how to get your auth token and interact with CRUD operations for applications, scans, findings, and permissions.

- Repository: [Mónica Pastor/mobileaudit](https://github.com/mpast/mobileaudit)
- Tags: api-reference
- Published: 2026-03-07

---

**Obtain an authentication token by POSTing your username and password to `/api/v1/auth-token/`, then include that token in the `Authorization: Token <token>` header to interact with the CRUD endpoints for applications, scans, findings, and permissions.**

The **Mobile Audit** project (`mpast/mobileaudit`) exposes a Django REST Framework API that allows programmatic access to mobile application security scanning data. All endpoints are versioned under the `api/v1/` path and implement standard REST conventions with token-based authentication for write operations.

## Available Mobile Audit REST API Endpoints

The API is built using a `DefaultRouter` registered in [`app/config/urls.py`](https://github.com/mpast/mobileaudit/blob/main/app/config/urls.py), which automatically generates standard CRUD patterns for each view-set defined in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py).

### Applications (`/api/v1/app/`)

The **Application** endpoint, backed by `ApplicationViewSet` in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py) (lines 18-24), supports full CRUD operations:

- `GET /api/v1/app/` – List all applications
- `POST /api/v1/app/` – Create a new application
- `GET /api/v1/app/{id}/` – Retrieve a specific application
- `PUT /api/v1/app/{id}/` – Full update
- `PATCH /api/v1/app/{id}/` – Partial update
- `DELETE /api/v1/app/{id}/` – Remove an application

### Scans (`/api/v1/scan/`)

The **Scan** endpoint uses `ScanViewSet` (lines 26-35 in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py)) and provides the same CRUD interface for managing security scans. This endpoint handles APK file uploads and scan configuration.

### Findings (`/api/v1/finding/`)

The **Finding** endpoint, implemented in `FindingViewSet` (lines 38-49 in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py)), includes standard CRUD plus a custom detail-level action:

- `GET /api/v1/finding/{id}/scan/` – Returns all findings associated with a specific scan ID

This custom route is registered via the `@action` decorator within the view-set.

### Permissions (`/api/v1/permission/`)

The **Permission** endpoint uses `PermissionViewSet` (lines 62-73 in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py)) and similarly provides a custom action:

- `GET /api/v1/permission/{id}/scan/` – Returns all permissions for a given scan

## How to Authenticate with `/api/v1/auth-token/`

Mobile Audit uses **Token Authentication** via Django REST Framework's built-in `obtain_auth_token` view. The endpoint is wired in [`app/config/urls.py`](https://github.com/mpast/mobileaudit/blob/main/app/config/urls.py) at line 56.

### Obtaining a Token

Send a `POST` request with your username and password to exchange them for an authentication token:

```bash
curl -X POST https://example.com/api/v1/auth-token/ \
     -H "Content-Type: application/json" \
     -d '{"username":"myuser","password":"mypassword"}'

```

**Response:**

```json
{
  "token": "b2d3f4e5c6a7..."
}

```

### Using the Token

All view-sets in [`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py) use the permission class `IsAuthenticatedOrReadOnly`. This means **read** operations (`GET`) are accessible without authentication, but **write** operations (`POST`, `PUT`, `PATCH`, `DELETE`) require a valid token.

Include the token in the `Authorization` header for all authenticated requests:

```bash
Authorization: Token b2d3f4e5c6a7...

```

## Code Examples for Common Operations

### List All Applications (No Authentication Required)

```bash
curl https://example.com/api/v1/app/

```

### Create a New Scan (Authenticated)

Upload an APK file and initiate a scan using your token:

```bash
TOKEN="b2d3f4e5c6a7..."
curl -X POST https://example.com/api/v1/scan/ \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/application.apk" \
     -F "name=Security Scan"

```

### Retrieve Findings for a Specific Scan (Custom Action)

Use the custom `scan` action on the Finding endpoint to get all findings associated with scan ID `42`:

```bash
curl https://example.com/api/v1/finding/42/scan/ \
     -H "Authorization: Token $TOKEN"

```

### Update a Permission Status (Authenticated)

Patch an existing permission record to change its status:

```bash
curl -X PATCH https://example.com/api/v1/permission/7/ \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"status":"granted"}'

```

## Key Implementation Files

Understanding the source structure helps when extending the API or debugging authentication issues:

- **[`app/config/urls.py`](https://github.com/mpast/mobileaudit/blob/main/app/config/urls.py)** – Registers the `DefaultRouter` (lines 23-26), includes the versioned API path (line 57), and maps the token endpoint to `obtain_auth_token` (line 56).
- **[`app/api.py`](https://github.com/mpast/mobileaudit/blob/main/app/api.py)** – Contains the view-set implementations: `ApplicationViewSet`, `ScanViewSet`, `FindingViewSet` (with custom `@action` for scan findings), and `PermissionViewSet` (with custom `@action` for scan permissions).
- **[`app/models.py`](https://github.com/mpast/mobileaudit/blob/main/app/models.py)** – Defines the data models (Application, Scan, Finding, Permission) that back the API.
- **[`app/serializers.py`](https://github.com/mpast/mobileaudit/blob/main/app/serializers.py)** – Handles conversion between model instances and JSON representations for API responses.

## Summary

- Mobile Audit exposes a **Django REST Framework** API under the `api/v1/` path, providing CRUD endpoints for **Applications**, **Scans**, **Findings**, and **Permissions**.
- The **`/api/v1/auth-token/`** endpoint accepts username/password credentials and returns an authentication token using DRF's `obtain_auth_token` view.
- All write operations require the token in the `Authorization: Token <token>` header, while read-only `GET` requests are publicly accessible due to the `IsAuthenticatedOrReadOnly` permission class.
- Custom actions at `/finding/{id}/scan/` and `/permission/{id}/scan/` allow retrieval of findings and permissions filtered by specific scan IDs.

## Frequently Asked Questions

### How do I obtain an API token for Mobile Audit?

Send a `POST` request to `/api/v1/auth-token/` with your username and password in the JSON body. The endpoint returns a token string that you must include in the `Authorization: Token <token>` header for all subsequent write requests.

### Which API endpoints require authentication?

All endpoints use the `IsAuthenticatedOrReadOnly` permission class. This means `GET` requests are accessible without authentication, but `POST`, `PUT`, `PATCH`, and `DELETE` operations require a valid token in the Authorization header.

### What are the custom actions available in the Mobile Audit API?

The `FindingViewSet` and `PermissionViewSet` each expose a detail-level custom action named `scan`. Accessing `/api/v1/finding/{id}/scan/` or `/api/v1/permission/{id}/scan/` returns all findings or permissions associated with the specified scan ID.

### Where is the API routing configured in the Mobile Audit source code?

The routing is defined in [`app/config/urls.py`](https://github.com/mpast/mobileaudit/blob/main/app/config/urls.py). Lines 23-26 register the view-sets with a `DefaultRouter`, line 57 includes the router under the `api/v1/` prefix, and line 56 maps the token endpoint to Django REST Framework's `obtain_auth_token` view.