Restricting organisation access by country
Overview
Country access lets an organisation owner block access to an organisation from chosen countries. When a request's client IP resolves to a blocked country, that request cannot read or change anything in the organisation — the API answers with a geo-blocked error, and the dashboard shows the organisation as unavailable from the caller's location.
The control is scoped to a single organisation. Sign-in itself still works, and the same user keeps full access to every other organisation they belong to.
Location is derived from the client IP address, so this is a policy control rather than a defence against a determined attacker: a VPN or proxy terminating in an allowed country defeats it. Where the country cannot be resolved at all, the request is allowed and the event is logged.
Country access is enforced alongside IP access (see Restricting organisation access by IP); country is evaluated first, so an organisation that refuses a caller for both reasons reports the country-block error.
Country access is being rolled out gradually. If the card described below is not present on your organisation, the feature is not yet switched on for your account.
Before you start
- You must be the owner of the organisation you want to fence. The Country access card is hidden for all other members, and the geofence API is owner-only.
- Note the country you are connecting from. You cannot block your own current country — the save is refused to prevent locking yourself out.
- Country resolution depends on the platform's GeoIP data. If your location cannot be determined, the card says so, and no country block can take effect for your traffic.
- If you plan to call the API with an API key, the key needs the
organizations:readscope to read the current list andorganizations:updateto replace it. - Credentials that were issued before you apply a block (object-storage keys, presigned URLs, kubeconfigs, console URLs) keep working until they expire or are rotated. Plan to rotate them after enabling a block.
Steps
- In the sidebar, open Organizations under ACCOUNT.
- Select the organisation you want to fence to open its detail page.
- Open the Settings tab and find the Country access card.
- Check the line showing the country you are currently connecting from ("You are connecting from: …"). If it says your location could not be determined, a block cannot apply to your own requests, and the self-lockout check has no country to compare against.
- Select the countries you want to block from the country list. Leaving the list empty means no country restriction.
- Click Save. The new list replaces the previous one and is written to the organisation audit log in the same transaction.
- Verify the result: members connecting from a blocked country see the organisation marked as unavailable from their location in the organisation list and receive a 403 on any organisation-scoped call.
The change applies on each member's next request; nothing is cached per browser session. The AI gateway picks up the new policy within about a minute.
API
Two public endpoints manage the country list. Both are bound to the organisation in the path, not to the active-organisation header.
Read the current country list:
GET /api/v1/organizations/{org_id}/geofence
curl https://app.cloudpe.com/api/v1/organizations/<org_id>/geofence \
-H "Authorization: Bearer <API_KEY>"
The response returns the blocked country list, the country resolved for the caller (null when it cannot be determined) and the list of countries you may select.
Replace the country list:
PUT /api/v1/organizations/{org_id}/geofence
curl -X PUT https://app.cloudpe.com/api/v1/organizations/<org_id>/geofence \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"blocked_countries": ["CN", "RU"]}'
blocked_countries replaces the stored list in full; send an empty array to turn the fence off. Country codes are ISO 3166-1 alpha-2 and are normalised, de-duplicated and sorted on save.
To find the organisation ID, list your organisations with GET /api/v1/organizations or read one with GET /api/v1/organizations/{org_id}.
Country access cannot be changed through PATCH /api/v1/organizations/{org_id}; that endpoint rejects geofence settings and preserves the stored value.
Limits & billing
- Country access is an organisation setting. It does not create a billable resource and has no usage charge.
- Up to 250 countries can be blocked per organisation; a longer list is rejected with a validation error.
- Every save is audited. If the audit entry cannot be written, the change is not saved at all.
- Not covered by the block: credentials minted before the block (object-storage keys and presigned URLs, kubeconfigs, console URLs) and already-open remote desktop connections. Rotate keys and kubeconfigs after enabling a block, and expect open connections to be checked only on the next connect.
- Platform administrators and admin impersonation sessions bypass the fence so that support can reach a fenced organisation. Reseller impersonation does not bypass it.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
You cannot block the country you are connecting from. |
The save would have blocked your own current location. | Remove your current country from the selection, or make the change from a connection in a country you intend to keep allowed. |
Unknown country code(s): {…} |
The request contained a code that is not a recognised country. | Send upper-case ISO 3166-1 alpha-2 codes drawn from the list returned by the geofence GET endpoint. |
This organization does not allow access from your location. |
The caller's resolved country is on the organisation's block list. | Connect from an allowed country, or ask the organisation owner to remove that country from the list. |
Could not record the audit entry; no change was saved. |
The audit record for the change could not be written, so the whole save was rolled back. | Retry the save. If it keeps failing, raise a support ticket — the stored list is unchanged. |
Use PUT /organizations/{org_id}/geofence to change country access |
Country settings were sent to the generic organisation update endpoint. | Use the geofence endpoint shown in the API section instead. |
Organization not found |
The organisation ID in the path does not exist or is not visible to you. | Confirm the ID with GET /api/v1/organizations. |
FAQ
Does a blocked country stop a user from signing in? No. Sign-in still works. The user simply cannot read or change anything inside the fenced organisation, and the organisation is shown as unavailable from their location.
What happens to a user whose only organisation blocks them? The dashboard shows a full-page unavailable state whose only action is to sign out. If the user belongs to other organisations, the dashboard switches to the first one they can still reach and explains why.
What if the platform cannot work out a caller's country? The request is allowed. Only a positively resolved blocked country is refused.
Does this stop someone using a VPN? No. IP geolocation is defeated by a VPN or proxy that terminates in an allowed country. Combine country access with IP access if you need to pin traffic to known networks.
Does the block apply to API keys as well as browser sessions? Yes. Both are evaluated at the same organisation checkpoints, including AI gateway traffic.
I travelled and now my own organisation is blocked. How do I get back in? The self-lockout check only protects the save itself. If you later connect from a blocked country, contact support from an allowed location or ask them to act for you: an admin impersonation session bypasses the block and can remove the country from the list.
Who can see what country the platform resolved for me?
The organisation owner, on the Country access card, or through GET /api/v1/organizations/{org_id}/geofence.