The Symphony Login API enables bots and applications to authenticate using RSA public/private key pairs, producing session tokens and OAuth2-compatible JWT access tokens. Supports bot authentication, extension app authentication, and delegated user context authentication.
swagger: '2.0'
info:
version: 20.14.1
title: Symphony Login API
description: |
For bots and other on-premise processes to authenticate. Once
authenticated, the bot will be able to use the methods described in
serviceAPI.yaml and agentAPI.yaml.
Authentication requests will expect the user to pass a token containing
user identification information and signed by the user's private key
There will be two implementations of this API, one on your Pod
and one on the Key Manager. In order to fully authenticate,
an API client will have to call both of these implementations
and pass both of the session tokens returned as headers in all
subsequent requests to the Symphony API.
paths:
/pubkey/authenticate:
post:
summary: Symphony Authenticate With Public Key
description: >
Based on an authentication request token signed by the caller's RSA
private key,
authenticate the API caller and return a session token.
A HTTP 401 Unauthorized error is returned on errors during
authentication (e.g. invalid user,
malformed authentication token, user's public key not imported in the
pod, invalid token signature etc.).
consumes:
- application/json
produces:
- application/json
parameters:
- name: authenticateRequest
in: body
required: true
schema:
$ref: '#/definitions/AuthenticateRequest'
tags:
- Pubkey
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/Token'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden to access this endpoint .
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/v1/pubkey/app/authenticate/extensionApp:
post:
summary: Symphony Authenticate Extension App With Public Key
description: >
Based on an authentication request token signed by the caller's RSA
private key,
authenticate the API caller and return a session token.
A HTTP 401 Unauthorized error is returned on errors during
authentication (e.g. invalid user,
malformed authentication token, user's public key not imported in the
pod, invalid token signature etc.).
consumes:
- application/json
produces:
- application/json
parameters:
- name: authenticateRequest
in: body
required: true
schema:
$ref: '#/definitions/AuthenticateExtensionAppRequest'
tags:
- Pubkey
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/ExtensionAppTokens'
'400':
description: Request object is invalid
schema:
$ref: '#/definitions/Error'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/pubkey/app/authenticate:
post:
summary: Symphony Authenticate an App With Public Key
description: >
Based on an authentication request token signed by the application's RSA
private key,
authenticate the API caller and return a session token.
A HTTP 401 Unauthorized error is returned on errors during
authentication (e.g. invalid app,
malformed authentication token, app's public key not imported in the
pod, invalid token signature etc.).
consumes:
- application/json
produces:
- application/json
parameters:
- name: authenticateRequest
in: body
required: true
schema:
$ref: '#/definitions/AuthenticateRequest'
tags:
- Pubkey
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/Token'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden to access this endpoint .
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/pubkey/app/username/{username}/authenticate:
post:
summary: >-
Symphony Authenticate an application in a delegated context to act on behalf of a user
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: App Session authentication token.
in: header
required: true
type: string
- name: username
description: the username
in: path
required: true
type: string
tags:
- Pubkey
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/Token'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden to access this endpoint .
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/pubkey/app/user/{userId}/authenticate:
post:
summary: >-
Symphony Authenticate an application in a delegated context to act on behalf of a user
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: App Session authentication token.
in: header
required: true
type: string
- name: userId
description: the user ID
in: path
required: true
type: integer
format: int64
tags:
- Pubkey
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/Token'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden to access this endpoint .
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/idm/tokens:
post:
summary: >-
Symphony Returns a valid OAuth2 access token from a given session token to be used for authentication
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: User session authentication token
in: header
required: true
type: string
- name: scope
description: >
Optional field used to get access with specific entitlements, use
space separated list to define more that one
in: query
required: false
type: string
tags:
- Idm
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/JwtToken'
'401':
description: Client is unauthorized to access this resource
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden to access this endpoint .
schema:
$ref: '#/definitions/Error'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
/idm/keys:
get:
summary: Symphony Returns the Common Access Token (JWT) Public Keys as a JWKS
x-since: 20.14
description: >-
This is a public endpoint, no authentication is required. The JWKS can
be used to verify JWT issued by the idm/tokens endpoint. Since SBE
20.14.
produces:
- application/json
tags:
- Idm
responses:
'200':
description: OK.
schema:
$ref: '#/definitions/Jwks'
'500':
description: Server error, see response body for further details.
schema:
$ref: '#/definitions/Error'
definitions:
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
Token:
type: object
properties:
name:
description: >
The name of the header in which the token should be presented on
subsequent API calls.
type: string
token:
type: string
description: >
Authentication token that should be passed as header in each API rest
calls.
This should be considered opaque data by the client. It is not
intended to contain any data interpretable by the
client. The format is secret and subject to change without notice.
authorizationToken:
type: string
description: >
(Beta) Short lived access token built from a user session. This field
is still on Beta, please continue using
the returned "token" instead.
AuthenticateRequest:
type: object
description: Request body for pubkey authentication
properties:
token:
type: string
description: >-
a JWT containing the caller's username or application appGroupId and
an expiration date, signed by the caller's private key.
AuthenticateExtensionAppRequest:
type: object
description: Request body for extension app authentication
properties:
appToken:
type: string
description: application generated token
authToken:
type: string
description: >-
a JWT containing the caller's username and an expiration date, signed
by the caller's private key.
ExtensionAppTokens:
type: object
properties:
appId:
description: Application ID
type: string
appToken:
description: >
This token generated by the application when calling authentication
endpoint
type: string
symphonyToken:
type: string
description: >
This token generated by Symphony and should be used by the application
to verify that it's talking to Symphony.
expireAt:
type: integer
format: int64
description: unix timestamp when the token expired
JwtToken:
type: object
properties:
token_type:
type: string
description: Type of token, string "Bearer"
expires_in:
type: integer
format: int64
description: Duration of time the access token is granted for in seconds
access_token:
type: string
description: >
A JWT containing the caller's username or application, an expiration
date and a set of entitlements related to the
specified scope, signed by the caller's private key.
Jwks:
type: object
properties:
keys:
type: array
items:
$ref: '#/definitions/JwksEntry'
JwksEntry:
type: object
description: >-
A JWK object as defined in
https://datatracker.ietf.org/doc/html/rfc7517#section-4.
additionalProperties:
type: string
tags:
- name: Idm
- name: Pubkey