{"openapi":"3.1.0","info":{"title":"Microsoft Graph Directory (BYOK) API","version":"0.1.0","description":"Microsoft Graph Directory (BYOK) lets an AI assistant read your own Microsoft Graph Directory data through the Microsoft Graph Directory API with a key you supply (Microsoft Graph access token (an OAuth token valid for about an hour)). Read-only: 10 tools (get_organization, list_domains, list_subscribed_skus, list_directory_roles, list_directory_role_templates, list_groups, get_group,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-graph-directory.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-graph-directory/docs"},"termsOfService":"https://connectorbay.com/byok-graph-directory/terms"},"servers":[{"url":"https://byok-graph-directory.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-graph-directory/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_organization":{"post":{"operationId":"get_organization","summary":"Get the tenant's organization record: display name, tenant type, creation time, country, verified domains and directory ","description":"Get the tenant's organization record: display name, tenant type, creation time, country, verified domains and directory sync status. Needs Organization.Read.All. Use for \"What is our Microsoft 365 tenant and which domains does it verify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":5,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"How many items to return (1 to 5). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"}},"title":"get_organizationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_domains":{"post":{"operationId":"list_domains","summary":"List the tenant's domains with authentication type (managed or federated), default and verified flags and supported serv","description":"List the tenant's domains with authentication type (managed or federated), default and verified flags and supported services. Needs Domain.Read.All. Use for \"Which domains are verified in our Microsoft tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 999). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"}},"title":"list_domainsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_subscribed_skus":{"post":{"operationId":"list_subscribed_skus","summary":"List the license plans (SKUs) the tenant owns with units consumed and units prepaid (enabled, suspended, warning) and se","description":"List the license plans (SKUs) the tenant owns with units consumed and units prepaid (enabled, suspended, warning) and service plans. Needs LicenseAssignment.Read.All or Organization.Read.All. Use for \"How many Microsoft 365 licenses are we using versus paying for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_subscribed_skusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_directory_roles":{"post":{"operationId":"list_directory_roles","summary":"List the directory roles activated in the tenant (for example Global Administrator) with description and template id. Ne","description":"List the directory roles activated in the tenant (for example Global Administrator) with description and template id. Needs RoleManagement.Read.Directory or Directory.Read.All. Use for \"Which Entra directory roles are active in our tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_directory_rolesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_directory_role_templates":{"post":{"operationId":"list_directory_role_templates","summary":"List all directory role templates Microsoft defines, with name and description (including roles not yet activated). Use ","description":"List all directory role templates Microsoft defines, with name and description (including roles not yet activated). Use for \"What Entra directory roles exist that I could assign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_directory_role_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_groups":{"post":{"operationId":"list_groups","summary":"List the tenant's groups (Microsoft 365, security, mail-enabled) with type flags, visibility, creation time and dynamic ","description":"List the tenant's groups (Microsoft 365, security, mail-enabled) with type flags, visibility, creation time and dynamic membership rule; filter or search by name. Needs Group.Read.All. Use for \"Which Microsoft 365 groups exist whose name starts with Sales\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items to return (1 to 999). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"},"filter":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Optional OData $filter expression, for example \"startswith(displayName,'Sales')\".","title":"Filter"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional $search term in the form \"displayName:Sales\" (with the double quotes).","title":"Search"}},"title":"list_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_group":{"post":{"operationId":"get_group","summary":"Get one group by id with description, mail address, type flags, visibility, creation and expiry time, and dynamic member","description":"Get one group by id with description, mail address, type flags, visibility, creation and expiry time, and dynamic membership rule. Needs Group.Read.All. Use for \"Tell me about Microsoft group 00000000-0000-0000-0000-000000000001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Object id (GUID) of the group, from list_groups.","maxLength":200,"title":"Group Id","type":"string"}},"required":["group_id"],"title":"get_groupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_devices":{"post":{"operationId":"list_devices","summary":"List devices registered or joined in Entra with name, operating system, ownership, management and compliance state, trus","description":"List devices registered or joined in Entra with name, operating system, ownership, management and compliance state, trust type and last sign-in time. Needs Device.Read.All. Use for \"Which devices in our tenant are not compliant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items to return (1 to 999). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"},"filter":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Optional OData $filter expression, for example \"startswith(displayName,'Sales')\".","title":"Filter"}},"title":"list_devicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_administrative_units":{"post":{"operationId":"list_administrative_units","summary":"List administrative units (scoped admin containers) with description, membership type, visibility and dynamic rule. Need","description":"List administrative units (scoped admin containers) with description, membership type, visibility and dynamic rule. Needs AdministrativeUnit.Read.All. Use for \"Which administrative units does our Entra tenant have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items to return (1 to 999). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"},"filter":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Optional OData $filter expression, for example \"startswith(displayName,'Sales')\".","title":"Filter"}},"title":"list_administrative_unitsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_deleted_groups":{"post":{"operationId":"list_deleted_groups","summary":"List groups deleted within the last 30 days (still restorable) with name, type flags and deletion time. Needs Group.Read","description":"List groups deleted within the last 30 days (still restorable) with name, type flags and deletion time. Needs Group.Read.All. Use for \"Which Microsoft groups were deleted recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items to return (1 to 999). Only the first page is returned, so use filter or search to narrow large tenants.","title":"Top"}},"title":"list_deleted_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}