DEV Community

FlareCanary
FlareCanary

Posted on

Atlassian Admin v1 APIs Go Dark on June 30 — Your User-Provisioning Script Probably Hits Eleven of Them

#atlassian #api #devops #security

If your team has any custom Atlassian Cloud admin automation — IdP sync, SCIM glue, lifecycle scripts, group provisioning — it almost certainly hits at least one of the eleven endpoints under /admin/v1/orgs/{orgId}/.... After June 30, 2026, those endpoints are gone.

Atlassian announced the v1 sunset alongside the new v2 Directory/Users/Groups APIs. The migration is documented; the part that isn't documented loudly is that v2 isn't a drop-in path swap. The shape of the URL changed, the auth model picked up an extra resolution step, and several common automation patterns become two-call sequences instead of one.

The eleven endpoints to grep for

User-management endpoints going away:

  • POST /admin/v1/orgs/{orgId}/users/search
  • POST /admin/v1/orgs/{orgId}/directory/users/{accountId}/suspend-access
  • POST /admin/v1/orgs/{orgId}/directory/users/{accountId}/restore-access
  • DELETE /admin/v1/orgs/{orgId}/directory/users/{accountId}

Group-management endpoints going away:

  • POST /admin/v1/orgs/{orgId}/groups/search
  • POST /admin/v1/orgs/{orgId}/directory/groups
  • DELETE /admin/v1/orgs/{orgId}/directory/groups/{groupId}
  • POST /admin/v1/orgs/{orgId}/directory/groups/{groupId}/roles/assign
  • POST /admin/v1/orgs/{orgId}/directory/groups/{groupId}/roles/revoke
  • POST /admin/v1/orgs/{orgId}/directory/groups/{groupId}/memberships
  • DELETE /admin/v1/orgs/{orgId}/directory/groups/{groupId}/memberships/{accountId}

Plus POST /admin/v1/orgs/{orgId}/users/invite, which Atlassian deprecated on January 13, 2026 — same June 30 sunset date.

A literal grep on your repo:

grep -rn "admin/v1/orgs" --include="*.{py,js,ts,go,rb,sh}" .
Enter fullscreen mode Exit fullscreen mode

If anything comes back, it dies on June 30.

This affects any tenant on centralized user management — which, since 2025, has been the default for new orgs and the migration target for existing ones. If you don't know which user management mode your org is on, the v1 sunset still applies once the migration completes, so treat it as in-scope.

What v2 actually looks like

The v1 path was organization-rooted:

/admin/v1/orgs/{orgId}/directory/users/{accountId}
Enter fullscreen mode Exit fullscreen mode

The v2 path is directory-rooted under an organization:

/admin/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}
Enter fullscreen mode Exit fullscreen mode

That directoryId is not optional, and Atlassian's v1 callers never had to know it. Every script migrating off v1 needs an extra step to discover the directory before it can act on a user or group inside that directory.

So a one-call workflow becomes a two-call workflow:

1. List directories for the org → pick a directoryId
2. Call the v2 endpoint with {orgId}/directories/{directoryId}/...
Enter fullscreen mode Exit fullscreen mode

For orgs with one directory, this is mostly mechanical. For orgs with multiple directories (Identity Manager, Google, Microsoft, plus a local directory), every script now has to disambiguate, and "the right one" depends on which IdP the user came from.

OAuth scopes — one easy miss

The Admin scope set didn't get a new "v2 scope." But scripts that previously only operated on users-by-account-id never had to declare read:directories:admin. Now they do, because every v2 call passes through a directory resolution.

Apps that don't add read:directories:admin to their token request will get scope errors on the new endpoints — without the v1 endpoint being there to fall back to. The scope error happens at request time, not at auth time, so a token issued before the migration looks fine until the first call.

What the failures will look like

Atlassian's announcement says v1 endpoints "will remain available until 30 June 2026. After this date, they will be fully deprecated." The exact response shape post-sunset isn't documented for /admin/v1/orgs/..., but Atlassian's pattern on other removed REST APIs (Jira /rest/api/3/search and friends) has been HTTP 410 Gone with a JSON error along the lines of:

{
  "code": 410,
  "message": "The requested API has been removed. Please use the newer endpoints."
}
Enter fullscreen mode Exit fullscreen mode

That's the expected fingerprint, not a guarantee. If your client treats 410 as terminal (most retry libraries do), the failed call will not be retried, and the operation — suspend, remove, group-add — silently won't happen. The script returns "successful" on the calls that didn't go through the dead endpoint and "failed" on the ones that did, and a half-completed offboarding looks identical to a successful one in the audit log.

The use cases that quietly break

The Atlassian announcement explicitly calls out a handful of automation patterns that depend on the v1 endpoints:

  • Offboarding scripts. Calling suspend-access and then directory/users/{accountId} DELETE in sequence is the canonical Atlassian-side termination flow. Both endpoints are on the list.
  • SCIM-adjacent IdP sync. Many teams wrote custom sync because Atlassian's SCIM connector didn't cover their IdP, or didn't handle group memberships the way they wanted. Custom sync scripts overwhelmingly use the v1 group memberships endpoints.
  • Bulk invite onboarding. POST /admin/v1/orgs/{orgId}/users/invite was the canonical way to invite a list of users with a default group set. Already deprecated since January.
  • Group provisioning from CI. Terraform-style "groups defined in code" pipelines that create/delete groups based on YAML — the create and delete endpoints are both on the list.

The offboarding case is the one that goes wrong silently. A user gets removed from your IdP, the sync script runs, the v2 path fails because the script wasn't migrated, and the user keeps their Atlassian access until someone notices on the next access review. That's the nightmare scenario for security teams who track "removed in IdP within X hours" as a compliance metric.

What to do this quarter

Three steps:

  1. Inventory. Grep admin/v1/orgs across all internal repos, CI configs, and scripts on admin/ops machines. Capture which endpoints are in use.
  2. Resolve directory IDs. Build (or buy) a small helper that lists directories on the org and returns the directory ID for a given user — every v2 call needs this.
  3. Add the read:directories:admin scope to your token requests before you migrate the calls. The scope addition is forward-compatible with v1 calls, so you can add it without breaking anything before you cut over.

If your custom sync also uses Jira's /rest/api/3/search or any other v3 Jira API marked for removal, batch them — same orgs, same teams, same maintenance window.

The pattern here is the one we keep seeing across providers: a deprecation notice goes out, the SDK or admin script gets an "available until" date that everyone marks on a sticky note, and on the day the API returns 410 the team finds out which scripts they actually shipped to production years ago. We built FlareCanary to flag the response-shape and field-semantic changes that don't even show up as a deprecation notice — but on this one, the calendar entry for June 30, 2026 is the one to set.

If your offboarding flow uses any v1 endpoint, treat it as the highest-priority migration. Half-completed user removals are an audit problem long before they're a security problem.

Top comments (0)