GET /api/v1/me/legal-entities

Retrieve the list of legal entities that the authenticated user has consented to share with this OAuth client.

Endpoint

GET /api/v1/me/legal-entities

Authentication

Requires a valid OAuth access token with the eprospera:entity.read scope.

Agent Keys are not supported on /api/v1/me/legal-entities*, which is the personal list endpoint for OAuth-consented entities. If you are using a scoped Agent Key, discover entities through POST /api/v1/registries/legal_entities/search, and use GET /api/v1/legal_entities/{id} or GET /api/v1/legal_entities/{id}/documents when you already know the entity ID. Agent Keys can only access entities whose underlying residency application was created via the API (residencyApplication.createdViaAPI === true); entities onboarded through the portal are not visible to agent-key callers.

Authorization: Bearer <access-token>

Required Scopes

• eprospera:entity.read

Example Request

curl https://portal.eprospera.com/api/v1/me/legal-entities \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

Success Response (200 OK)

Field	Type	Description
data	array	Array of legal entity objects
data[].id	string	Unique identifier for the legal entity
data[].optionId	string	Entity formation option (e.g., llc, for_profit_corp)
data[].type	string	Entity type (e.g., "Limited Liability Company")
data[].name	string	Legal name of the entity
data[].extension	string	Name extension (e.g., "LLC", "Inc.")
data[].nameStartsWithExtension	boolean	Whether the name starts with the extension
data[].residentPermitNumber	string | null	Entity's Resident Permit Number

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "optionId": "llc",
      "type": "Limited Liability Company",
      "name": "Acme Holdings",
      "extension": "LLC",
      "nameStartsWithExtension": false,
      "residentPermitNumber": "80123456789012"
    }
  ]
}

Pagination

This endpoint is not currently paginated. The full result set is returned in a single response under data. Treat this as the current contract; in the future a pagination envelope (page/pageSize/totalCount/pageCount, matching /api/v1/nomadlayer/applications) may be added — design clients so an additional top-level pagination field would not break them. See Conventions → Pagination.

Error Responses

401 Unauthorized - Missing Token

{
  "error": "missing_token"
}

401 Unauthorized - Invalid Token

{
  "error": "invalid_token"
}

401 Unauthorized - Insufficient Scopes

{
  "error": "missing_scopes: eprospera:entity.read"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Notes

• Only returns entities the user explicitly consented to share during authorization.
• If the user loses representative access to an entity, it stops appearing in results.
• Can return an empty array if no consented entities remain.
• Agent Keys are not supported on this route; an Agent Key sent here is treated as an invalid OAuth token.