# Tax and legal-entity data (/tax-and-entity-data)

Use OAuth or the official CLI to read your own tax records and data for legal entities you actively represent and explicitly consent to share.



The e-Próspera public API provides read-only access to personal tax records and
to selected legal entities. It cannot return other users' records or entities
the user did not consent to share.

## Available data [#available-data]

An authorized user can:

* view personal tax obligations, including open and overdue periods;
* list submitted income-tax and VAT filings;
* inspect a submitted filing and its calculated amounts;
* download an assessment or filed-return PDF;
* list legal entities selected during OAuth consent;
* read a selected entity's profile and available documents; and
* perform the same read-only tax operations for a selected entity they still
  actively represent.

These endpoints do not create, edit, submit, or pay a tax filing. Tax summaries
are calculated without creating draft statements.

## Access boundaries [#access-boundaries]

| Data                     | Required scope                    | Additional checks                                                                             |
| ------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------- |
| Personal tax records     | `eprospera:person.tax.read`       | The OAuth user can only request their own records.                                            |
| Legal-entity profile     | `eprospera:entity.read`           | The entity must be selected during consent.                                                   |
| Legal-entity documents   | `eprospera:entity.documents.read` | The entity must be selected during consent.                                                   |
| Legal-entity tax records | `eprospera:entity.tax.read`       | The entity must be selected during consent and the user must remain an active representative. |

Selecting an entity during consent does not permanently bypass membership
checks. If the user stops representing that entity, subsequent requests stop
returning its data.

## Use the official CLI [#use-the-official-cli]

Authorize the CLI in a browser:

```bash
eprospera auth login --oauth
```

The browser consent page shows the requested permissions and lets the user
select which legal entities to share. The CLI client has no embedded secret and
requests only the published user and entity scopes.

List and inspect the entities available to the CLI:

```bash
eprospera --json me legal-entities list
eprospera --json me legal-entities get <entity-id>
eprospera --json me legal-entities documents <entity-id>
```

Read personal tax information:

```bash
eprospera --json tax status --subject personal
eprospera --json tax list --subject personal --type income --year 2025
eprospera --json tax get <filing-id>
eprospera tax download <filing-id> --document assessment
```

For entity taxes, pass a consented legal-entity UUID:

```bash
eprospera --json tax status --subject <entity-id>
eprospera --json tax list --subject <entity-id> --type vat --year 2025
eprospera tax download <filing-id> --document return --output filed-return.pdf
```

`tax list` returns an opaque cursor for the next page when more filings are
available. Pass that value back with `--cursor`; do not parse or modify it.

## Direct API endpoints [#direct-api-endpoints]

| Operation               | Endpoint                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| List consented entities | [GET `/api/v1/me/legal-entities`](/reference/oauth-get-legal-entities)                                 |
| Read one entity         | [GET `/api/v1/me/legal-entities/{id}`](/reference/oauth-get-legal-entities-id)                         |
| Read entity documents   | [GET `/api/v1/me/legal-entities/{id}/documents`](/reference/oauth-get-legal-entities-id-documents)     |
| Read tax status         | [GET `/api/v1/me/tax/summary`](/reference/oauth-get-tax-summary)                                       |
| List submitted filings  | [GET `/api/v1/me/tax/filings`](/reference/oauth-list-tax-filings)                                      |
| Read one filing         | [GET `/api/v1/me/tax/filings/{filingId}`](/reference/oauth-get-tax-filing)                             |
| Download a tax document | [GET `/api/v1/me/tax/filings/{filingId}/documents/{document}`](/reference/oauth-download-tax-document) |

Use `subject=personal` for the authenticated user's records or
`subject=<entity-uuid>` for a consented legal entity. Tax endpoints accept the
matching personal or entity tax scope; having one does not grant the other.

## Handling sensitive information [#handling-sensitive-information]

Tax amounts, filing history, assessments, returns, and some legal-entity
documents are confidential financial information.

* Do not place access tokens, refresh tokens, tax responses, or downloaded
  documents in source control or shared logs.
* Treat JSON and human-readable terminal output as sensitive; shell redirection
  and CI log capture can persist it.
* Tax PDFs are created with owner-only file permissions on supported platforms.
  The CLI refuses to overwrite an existing file unless `--yes` is supplied.
* Use `eprospera --yes auth logout` to revoke the remote OAuth session and
  remove the locally stored credential.

The CLI stores credentials in the operating-system keychain when available. Its
protected local-file fallback is intended for a single-user workstation, not a
shared machine.