Manages identity and access control in the AGNTCY ecosystem: register agents, MCP servers and tools as apps (including directly from an OASF record), issue and verify W3C Verifiable Credential badges, manage policies and rules, register approval devices, and run the OIDC authorize/token and external-authorization flows. OpenAPI 3.0.3, 36 operations, with bearer-JWT and x-id-api-key security schemes.
openapi: 3.0.3
info:
title: AGNTCY Identity Service API
description: AGNTCY Identity Service API provides a set of endpoints for managing identity and access control within the
Agntcy ecosystem.
contact:
name: Agntcy Team
url: https://github.com/agntcy/identity-service
email: identity@agntcy.org
version: v1alpha1
x-provenance:
method: harvested
authored_by: AGNTCY (Outshift by Cisco)
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: agntcy.org / outshift.com
note: 'Four first-party machine-readable contracts: the Agent Connect Protocol OpenAPI 3.1.1, the OASF Schema API, and
two AGNTCY Identity OpenAPI 3.0.3 documents. schema.oasf.outshift.com is the one genuinely callable AGNTCY-hosted API
(unauthenticated, 200).'
x-evidence:
- type: source
url: https://spec.acp.agntcy.org/
- type: source
url: https://schema.oasf.outshift.com/doc
- type: source
url: https://identity-docs.outshift.com/api/openapi/service/v1alpha1/openapi.yaml
servers:
- url: http://localhost:4000
description: Local environment
paths:
/v1alpha1/apps:
get:
tags:
- AppService
description: List Apps.
operationId: AppService_ListApps
parameters:
- name: page
in: query
description: The current page of the pagination
schema:
type: integer
format: int32
- name: size
in: query
description: The page size of the pagination
schema:
type: integer
format: int32
- name: query
in: query
description: The search query
schema:
type: string
- name: types
in: query
description: The app type filter
schema:
type: array
items:
enum:
- APP_TYPE_UNSPECIFIED
- APP_TYPE_AGENT_A2A
- APP_TYPE_AGENT_OASF
- APP_TYPE_MCP_SERVER
type: string
format: enum
- name: sortColumn
in: query
description: The column ID to sort by
schema:
type: string
- name: sortDesc
in: query
description: Whether to sort in descending order (true) or ascending order (false)
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppsResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
post:
tags:
- AppService
description: Create a new App.
operationId: AppService_CreateApp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/App'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/App'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/all/count:
get:
tags:
- AppService
description: Get apps count per type.
operationId: AppService_GetAppsCount
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetAppsCountResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/oasf:
post:
tags:
- AppService
operationId: AppService_CreateOasfApp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOasfAppRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOasfAppResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/{appId}:
get:
tags:
- AppService
description: Get App by id
operationId: AppService_GetApp
parameters:
- name: appId
in: path
description: App Id to get.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/App'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
delete:
tags:
- AppService
description: Delete an existing App.
operationId: AppService_DeleteApp
parameters:
- name: appId
in: path
description: App Id to delete.
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
patch:
tags:
- AppService
description: Update an App.
operationId: AppService_UpdateApp
parameters:
- name: appId
in: path
description: App Id to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/App'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/App'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/{appId}/api-key/refresh:
get:
tags:
- AppService
description: Refresh the api-key for an App.
operationId: AppService_RefreshAppApiKey
parameters:
- name: appId
in: path
description: App Id to refresh the API Key for.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/App'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/{appId}/badge:
get:
tags:
- AppService
description: Get the current badge issued for the App.
operationId: AppService_GetBadge
parameters:
- name: appId
in: path
description: App Id or Resolver Metadata ID to get the badge for.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Badge'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/apps/{appId}/badges:
post:
tags:
- BadgeService
description: Create a new Badge.
operationId: BadgeService_IssueBadge
parameters:
- name: appId
in: path
description: App Id.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueBadgeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Badge'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/auth/app_info:
get:
tags:
- AuthService
description: App info endpoint
operationId: AuthService_AppInfo
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AppInfoResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/auth/approve_token:
post:
tags:
- AuthService
description: Handle manual approval of external authorization requets
operationId: AuthService_ApproveToken
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApproveTokenRequest'
required: true
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/auth/authorize:
post:
tags:
- AuthService
description: Authorize a request from an Agent or MCP Server
operationId: AuthService_Authorize
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizeResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/auth/ext_authz:
post:
tags:
- AuthService
description: Handle external authorization requests
operationId: AuthService_ExtAuthz
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExtAuthzRequest'
required: true
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/auth/token:
post:
tags:
- AuthService
description: Request token for an Agent or MCP Server
operationId: AuthService_Token
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/badges/verify:
post:
tags:
- BadgeService
description: Verify a badge.
operationId: BadgeService_VerifyBadge
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyBadgeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationResult'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/device:
get:
tags:
- DeviceService
description: List all registered devices
operationId: DeviceService_ListDevices
parameters:
- name: page
in: query
description: The current page of the pagination
schema:
type: integer
format: int32
- name: size
in: query
description: The page size of the pagination
schema:
type: integer
format: int32
- name: query
in: query
description: The search query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListDevicesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
post:
tags:
- DeviceService
description: Add new device for approval flow
operationId: DeviceService_AddDevice
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/device/{deviceId}:
post:
tags:
- DeviceService
description: Add new device for approval flow
operationId: DeviceService_RegisterDevice
parameters:
- name: deviceId
in: path
description: The unique identifier for the device to register.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
required: true
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
delete:
tags:
- DeviceService
description: Delete a registered Device.
operationId: DeviceService_DeleteDevice
parameters:
- name: deviceId
in: path
description: The device id.
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/device/{deviceId}/test:
post:
tags:
- DeviceService
description: Send a test notification to a registered device to see if it's well configured.
operationId: DeviceService_TestDevice
parameters:
- name: deviceId
in: path
description: The device id.
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/policies:
get:
tags:
- PolicyService
description: List Policies.
operationId: PolicyService_ListPolicies
parameters:
- name: page
in: query
description: The current page of the pagination
schema:
type: integer
format: int32
- name: size
in: query
description: The page size of the pagination
schema:
type: integer
format: int32
- name: query
in: query
description: The search query
schema:
type: string
- name: appIds
in: query
description: A filter used to fetch policies only for the specified Agentic Services
schema:
type: array
items:
type: string
- name: rulesForAppIds
in: query
description: A filter used to fetch policies where the rules applies for the specified Agentic Services
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListPoliciesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
post:
tags:
- PolicyService
description: Create a new Policy.
operationId: PolicyService_CreatePolicy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePolicyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/policies/all/count:
get:
tags:
- PolicyService
description: Get policies total count.
operationId: PolicyService_GetPoliciesCount
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPoliciesCountResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/policies/{policyId}:
get:
tags:
- PolicyService
description: Get Policy by id
operationId: PolicyService_GetPolicy
parameters:
- name: policyId
in: path
description: Policy Id to get.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
delete:
tags:
- PolicyService
description: Delete an existing Policy.
operationId: PolicyService_DeletePolicy
parameters:
- name: policyId
in: path
description: Policy Id to delete.
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
patch:
tags:
- PolicyService
description: Update a Policy.
operationId: PolicyService_UpdatePolicy
parameters:
- name: policyId
in: path
description: Policy Id to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePolicyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/policies/{policyId}/rules:
get:
tags:
- PolicyService
description: List Rules.
operationId: PolicyService_ListRules
parameters:
- name: policyId
in: path
description: The Policy Id to which these Rules belong.
required: true
schema:
type: string
- name: page
in: query
description: The current page of the pagination
schema:
type: integer
format: int32
- name: size
in: query
description: The page size of the pagination
schema:
type: integer
format: int32
- name: query
in: query
description: The search query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListRulesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
post:
tags:
- PolicyService
description: Create a new Rule.
operationId: PolicyService_CreateRule
parameters:
- name: policyId
in: path
description: The Policy Id to which these Rules belong.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRuleRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Rule'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/policies/{policyId}/rules/{ruleId}:
get:
tags:
- PolicyService
description: Get Rule by id
operationId: PolicyService_GetRule
parameters:
- name: policyId
in: path
description: The Policy Id to which these Rules belong.
required: true
schema:
type: string
- name: ruleId
in: path
description: Rule Id to get.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Rule'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
delete:
tags:
- PolicyService
description: Delete an existing Rule.
operationId: PolicyService_DeleteRule
parameters:
- name: policyId
in: path
description: The Policy Id to which these Rules belong.
required: true
schema:
type: string
- name: ruleId
in: path
description: Rule Id to delete.
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
patch:
tags:
- PolicyService
description: Update a Rule.
operationId: PolicyService_UpdateRule
parameters:
- name: policyId
in: path
description: The Policy Id to which these Rules belong.
required: true
schema:
type: string
- name: ruleId
in: path
description: Rule Id to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRuleRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Rule'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/settings:
get:
tags:
- SettingsService
description: Get Settings
operationId: SettingsService_GetSettings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/settings/api-key:
post:
tags:
- SettingsService
description: Set up API Key
operationId: SettingsService_SetApiKey
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/settings/issuer:
post:
tags:
- SettingsService
description: Set up Issuer
operationId: SettingsService_SetIssuer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetIssuerRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IssuerSettings'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha1/tasks:
get:
tags:
- AppService
description: Get the list of tasks of all apps
operationId: AppService_GetTasks
parameters:
- name: excludeAppIds
in: query
description: A filter to exclude fetching tasks for the specified app ids
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTasksResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
components:
schemas:
ApiKey:
type: object
properties:
apiKey:
type: string
description: An Identity API Key.
App:
required:
- name
- type
type: object
properties:
id:
readOnly: true
type: string
description: A unique identifier for the App.
name:
type: string
description: A human-readable name for the App.
description:
type: string
description: A human-readable description for the App.
type:
enum:
- APP_TYPE_UNSPECIFIED
- APP_TYPE_AGENT_A2A
- APP_TYPE_AGENT_OASF
- APP_TYPE_MCP_SERVER
type: string
description: The type of the App.
format: enum
resolverMetadataId:
readOnly: true
type: string
description: The DID value
apiKey:
readOnly: true
type: string
description: The API Key Secret for the App.
status:
readOnly: true
enum:
- APP_STATUS_UNSPECIFIED
- APP_STATUS_ACTIVE
- APP_STATUS_PENDING
- APP_STATUS_REVOKED
type: string
description: The status of the App
format: enum
createdAt:
readOnly: true
type: string
description: CreatedAt records the timestamp of when the App was initially created
format: date-time
description: Identity Service App.
AppInfoResponse:
type: object
properties:
app:
allOf:
- $ref: '#/components/schemas/App'
description: The App information.
AppTypeCountEntry:
type: object
properties:
key:
enum:
- APP_TYPE_UNSPECIFIED
- APP_TYPE_AGENT_A2A
- APP_TYPE_AGENT_OASF
- APP_TYPE_MCP_SERVER
type: string
description: The type of the App
format: enum
value:
type: string
description: The count of apps of the given type
ApproveTokenRequest:
type: object
properties:
deviceId:
type: string
description: The device id used to handle the approval requestion
sessionId:
type: string
description: The session id related to the token that needs to be approved
otp:
type: string
description: The OTP sent to the device related to the request
approve:
type: boolean
description: 'The action made by the user (true: allow the token, false: deny the token)'
AuthorizeRequest:
type: object
properties:
resolverMetadataId:
type: string
description: The resolver metadata id for which authorization is requested.
toolName:
type: string
description: The MCP Server tool name.
userToken:
type: string
description: "The User context in the form of an id or access token.\n Mandatory for User Approval Flows."
AuthorizeResponse:
type: object
properties:
authorizationCode:
type: string
description: "If authorization is successful, return a code to be used for\n the token endpoint."
Badge:
type: object
properties:
verifiableCredential:
$ref: '#/components/schemas/VerifiableCredential'
appId:
type: string
BadgeClaims:
type: object
properties:
id:
type: string
description: "The ID as defined [here]\n\n [here]: https://www.w3.org/TR/vc-data-model/#credential-subject"
badge:
type: string
description: The content of the badge
description: "BadgeClaims represents the content of a Badge VC defined [here]\n\n [here]: https://spec.identity.agntcy.org/docs/vc/intro/"
CreateOasfAppRequest:
type: object
properties:
schemaBase64:
type: string
description: The OASF schema in a base64 encoded format
CreateOasfAppResponse:
type: object
properties:
app:
allOf:
- $ref: '#/components/schemas/App'
description: The created OASF App.
badge:
allOf:
- $ref: '#/components/schemas/Badge'
description: The issued badge for the OASF App.
CreatePolicyRequest:
type: object
properties:
name:
type: string
description: A human-readable name for the Policy.
description:
type: stri
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agntcy/refs/heads/main/openapi/agntcy-identity-service-openapi.yaml