swagger: '2.0'
info:
version: '20.17.1'
title: Pod API
description: |
This document refers to Symphony API calls that do not need
encryption or decryption of content.
- sessionToken can be obtained by calling the
authenticationAPI on the symphony back end and the key manager
respectively. Refer to the methods described in authenticatorAPI.yaml.
- Actions are defined to be atomic, ie will succeed in their entirety
or fail and have changed nothing.
- If it returns a 40X status then it will have made no change to the
system even if ome subset of the request would have succeeded.
- If this contract cannot be met for any reason then this is an error
and the response code will be 50X.
host: 'yourpodURL.symphony.com'
basePath: '/pod'
paths:
'/v1/companycert/list':
get:
summary: List all trusted certs
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: skip
description: Pagination start
in: query
required: false
type: integer
- name: limit
description: Row limit
in: query
required: false
type: integer
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertInfoList'
examples:
application/json:
- companyCertAttributes:
name: agentservice
type:
type: USER
status:
type: TRUSTED
companyCertInfo:
fingerPrint: "300a..."
lastSeen: 0
updatedAt: 0
updatedBy: 0
commonName: agentservice
expiryDate: 1781886755000
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v2/companycert/create':
post:
summary: Create a company trusted or untrusted certificate.
Different from V1 in that we reject expired certificates.
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: cert
in: body
required: true
schema:
$ref: '#/definitions/CompanyCert'
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertDetail'
examples:
application/json:
- companyCertAttributes:
name: jira
type:
type: USER
status:
type: KNOWN
companyCertInfo:
fingerPrint: "450369..."
issuerFingerPrint: "c35680..."
lastSeen: 1529994790226
updatedAt: 1529598066602
updatedBy: 9208409884327
commonName: jiraWebHookIntegration
expiryDate: 1768510565000
certInfo:
- name: General
attributes:
- name: Issuer
value: C=US O=Symphony Communications LLC CN=bot_user_provisioning
- name: Subject
value: C=US OU=NOT FOR PRODUCTION USE O=Symphony Communications LLC CN=jiraWebHookIntegration
- name: Signature Algorithm
value: SHA256withRSA
- name: Validity
attributes:
- name: Not Before
value: Mon Jan 15 20:56:05 UTC 2018
- name: Not After
value: Thu Jan 15 20:56:05 UTC 2026
- name: Public Key
attributes:
- name: Algorithm
value: RSA
- name: Format
value: X.509
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/delete':
post:
summary: Delete a company certificate
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: fingerPrint
in: body
required: true
schema:
$ref: '#/definitions/StringId'
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/SuccessResponse'
examples:
application/json:
format: TEXT
message: OK
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/{fingerPrint}/get':
get:
summary: Get the details of a company certificate
consumes:
- application/json
produces:
- application/json
parameters:
- name: fingerPrint
description: Certificate fingerPrint (ID)
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertDetail'
examples:
application/json:
- companyCertAttributes:
name: jira
type:
type: USER
status:
type: KNOWN
companyCertInfo:
fingerPrint: "450369..."
issuerFingerPrint: "c35680..."
lastSeen: 1529994790226
updatedAt: 1529598066602
updatedBy: 9208409884327
commonName: jiraWebHookIntegration
expiryDate: 1768510565000
certInfo:
- name: General
attributes:
- name: Issuer
value: C=US O=Symphony Communications LLC CN=bot_user_provisioning
- name: Subject
value: C=US OU=NOT FOR PRODUCTION USE O=Symphony Communications LLC CN=jiraWebHookIntegration
- name: Signature Algorithm
value: SHA256withRSA
- name: Validity
attributes:
- name: Not Before
value: Mon Jan 15 20:56:05 UTC 2018
- name: Not After
value: Thu Jan 15 20:56:05 UTC 2026
- name: Public Key
attributes:
- name: Algorithm
value: RSA
- name: Format
value: X.509
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/{fingerPrint}/update':
post:
summary: Update a company certificate
consumes:
- application/json
produces:
- application/json
parameters:
- name: fingerPrint
description: Certificate fingerPrint (ID)
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: certAttributes
in: body
required: true
schema:
$ref: '#/definitions/CompanyCertAttributes'
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/SuccessResponse'
examples:
application/json:
format: TEXT
message: OK
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/{fingerPrint}/issuedBy':
get:
summary: |
Return a list of all certificates which were verified to the cert whose
fingerprint is passed.
consumes:
- application/json
produces:
- application/json
parameters:
- name: fingerPrint
description: Certificate fingerPrint (ID)
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertInfoList'
examples:
application/json:
- companyCertAttributes:
name: agentservice
type:
type: USER
status:
type: TRUSTED
companyCertInfo:
fingerPrint: 300a...
lastSeen: 0
updatedAt: 0
updatedBy: 0
commonName: agentservice
expiryDate: 1781886755000
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/podmanaged/list':
get:
summary: List all trusted certs
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: skip
description: Pagination start
in: query
required: false
type: integer
- name: limit
description: Row limit
in: query
required: false
type: integer
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertInfoList'
examples:
application/json:
- companyCertAttributes:
name: agentservice
type:
type: USER
status:
type: TRUSTED
companyCertInfo:
fingerPrint: 300a...
lastSeen: 0
updatedAt: 0
updatedBy: 0
commonName: agentservice
expiryDate: 1781886755000
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/companycert/type/list':
post:
summary: List all certs of the given types
consumes:
- application/json
produces:
- application/json
parameters:
- name: typeIdList
description: Certificate type list
in: body
required: true
schema:
$ref: '#/definitions/CompanyCertTypeList'
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: skip
description: Pagination start
in: query
required: false
type: integer
- name: limit
description: Row limit
in: query
required: false
type: integer
tags:
- Security
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CompanyCertInfoList'
examples:
application/json:
- companyCertAttributes:
name: agentservice
type:
type: USER
status:
type: TRUSTED
companyCertInfo:
fingerPrint: 300a...
lastSeen: 0
updatedAt: 0
updatedBy: 0
commonName: agentservice
expiryDate: 1781886755000
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/podcert':
get:
summary: |
Retrieve the pod certificate that can be use to validate signed JWT tokens generated from the pod
produces:
- application/json
tags:
- Pod
responses:
'200':
description: OK
schema:
$ref: '#/definitions/PodCertificate'
examples:
application/json:
certificate: PEM_CERTIFICATE
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/connection/list':
get:
summary: List of requesting user's connection
description: |
This retrieves all connections of the requesting user. (i.e. both connections in which the requesting user is the sender and those
in which the requesting user is the inivtee) By default, if you haven't specified the connection status to filter on, this call will only
return results for both "pending_incoming" and "pending_outgoing". You can optionally filter by userIds to further restrict the results of
a specific connection status. If the users are in the same private pod, the users have an implicit connection status of "accepted". Those
users will not be returned in the response if you don't specify the connection status as "accepted" (default is "pending")
and the explicit userIds in the request.
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: status
description: |
Filter the connection list based on the connection status.
The connection status can only be pending_incoming, pending_outgoing, accepted, rejected, or all (all of the above)
in: query
type: string
enum:
- PENDING_INCOMING
- PENDING_OUTGOING
- ACCEPTED
- REJECTED
- ALL
- name: userIds
description: |
The userIds parameter should be specified as a comma delimited list of user ids and can be used to restrict the results of a specific connection.
Note that this is particularly important if the caller intends to retrieve results for implicit connection (user within the same pod).
Implicit connections will not be included in the response if userId is not provided.
in: query
type: string
tags:
- Connection
responses:
'200':
description: OK
schema:
$ref: '#/definitions/UserConnectionList'
examples:
application/json:
- userId: 769658112378
status: ACCEPTED
updatedAt: 1471018076255
- userId: 7078106103809
status: PENDING_INCOMING
updatedAt: 1467562406219
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: Connection cannot be found.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. Connection cannot be found. See response body for fruther details.
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/connection/create':
post:
summary: Sends an invitation to connect with another user
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: connectionRequest
in: body
required: true
schema:
$ref: '#/definitions/UserConnectionRequest'
tags:
- Connection
responses:
'200':
description: OK
schema:
$ref: '#/definitions/UserConnection'
examples:
application/json:
userId: 7078106126503
status: PENDING_OUTGOING
firstRequestedAt: 1470018076306
updatedAt: 1471018076255
requestCounter: 1
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: User cannot be found.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. User cannot be found. See response body for fruther details.
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/connection/accept':
post:
summary: Accept the connection request for the requesting user
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: connectionRequest
in: body
required: true
schema:
$ref: '#/definitions/UserConnectionRequest'
tags:
- Connection
responses:
'200':
description: Success
schema:
$ref: '#/definitions/UserConnection'
examples:
application/json:
userId: 7078106126503
status: ACCEPTED
firstRequestedAt: 1470018076306
updatedAt: 1471018076255
requestCounter: 1
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: The user lacks the required entitlement to perform this operation
'404':
description: 'Not Found: Connection cannot be found.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
message: // Not Found. Connection cannot be found. See response body for fruther details.
'500':
description: 'Server error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 500
message: // Server error, see response body for further details.
'/v1/connection/reject':
post:
summary: Reject the connection request for the requesting user.
description: |
Reject the connection between the requesting user and request sender. If both users are in the same private pod,
an error will be returned because both users have an implicit connection which cannot be rejected.
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: connectionRequest
in: body
required: true
schema:
$ref: '#/definitions/UserConnectionRequest'
tags:
- Connection
responses:
'200':
description: Success
schema:
$ref: '#/definitions/UserConnection'
examples:
application/json:
userId: 7078106126503
status: REJECTED
firstRequestedAt: 1470018076306
updatedAt: 1471018076255
requestCounter: 1
'400':
description: 'Client error, see response body for further details.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 400
message: // Client error, see response body for further details.
'401':
description: 'Unauthorized: Invalid session token.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 401
message: Invalid session
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 403
# --- truncated at 32 KB (363 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finos/refs/heads/main/openapi/finos-symphony-pod-api-openapi.yml