> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Login
> Authenticate healthcare provider and obtain access token for API usage
Use this endpoint to authenticate a provider. On a successful request, this endpoint returns a Suki Token (`suki_token`/`sdp_suki_token`) that you must use to authorize all subsequent API calls for that user.
The `suki_token` is a JWT that is valid for **one hour**. It contains the **user**, **organization**, and Partner information needed to access Suki services.
If you are using the JWT Bearer/Assertion authentication method, the response may also include an additional `jwt_bearer` field.
## Code examples
```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import requests
url = "https://sdp.suki-stage.com/api/v1/auth/login"
payload = {
"partner_id": "your-partner-id",
"partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"provider_id": "provider-123" # Optional
}
response = requests.post(url, json=payload)
if response.status_code == 200:
data = response.json()
suki_token = data["suki_token"]
print(f"Authentication successful. Token: {suki_token}")
else:
print(f"Authentication failed: {response.status_code}")
print(response.json())
```
```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
partner_id: 'your-partner-id',
partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
provider_id: 'provider-123' // Optional
})
});
if (response.ok) {
const data = await response.json();
const sukiToken = data.suki_token;
console.log(`Authentication successful. Token: ${sukiToken}`);
} else {
const error = await response.json();
console.error(`Authentication failed: ${response.status}`, error);
}
```
## OpenAPI
````yaml POST /api/v1/auth/login
openapi: 3.0.1
info:
title: Suki Developer Platform
description: >-
REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
Login or Register to obtain a Suki access token, then integrate ambient
clinical documentation, form filling, transcription, and reference metadata
endpoints.
contact: {}
version: '1.0'
servers:
- url: https://sdp.suki.ai
description: >-
Production base URL for Suki Developer Platform REST APIs. WebSocket
endpoints use the same host with `wss://`.
security:
- SukiTokenAuth: []
paths:
/api/v1/auth/login:
post:
tags:
- /api/v1/auth
summary: Login
description: >-
Authenticates a registered provider and returns a Suki access token
(`suki_token`). Use that token as `sdp_suki_token` on all subsequent API
calls. Tokens expire after one hour.
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationRequest'
required: true
responses:
'200':
description: Request succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationResponse'
'401':
description: Unauthorized. The Suki access token is missing, expired, or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationError'
'403':
description: Forbidden. The authenticated user cannot access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.ForbiddenError'
'404':
description: Not found. The session, encounter, or resource ID does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.NotFoundError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.InternalServerError'
security: []
components:
schemas:
controllers.AuthenticationRequest:
type: object
required:
- partner_id
- partner_token
properties:
partner_id:
type: string
description: >-
Unique identifier for the partner. This will be shared securely by
Suki to the partner through a separate partner registration process.
example: your-partner-id
partner_token:
type: string
description: >-
JWT token issued by trusted authorization server. The token must
include Provider Email.
example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
provider_id:
type: string
description: >-
**Optional** - Unique identifier for the provider. This is required
for Bearer type partners only and will be ignored for other partner
types. This must match a pre-defined expression.
example: provider-123
description: >-
Partner credentials from onboarding. Bearer partners must also include
`provider_id`.
example:
partner_id: your-partner-id
partner_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
provider_id: provider-123
controllers.AuthenticationResponse:
type: object
properties:
suki_token:
type: string
example: >-
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
description: >-
JWT access token for the authenticated provider. Pass this value as
`sdp_suki_token` on subsequent requests. Expires after one hour.
description: Suki access token returned after successful Login.
controllers.AuthenticationError:
type: object
properties:
code:
type: integer
example: 401
description: HTTP status code for the error.
message:
type: string
example: invalid token
description: Human-readable description of the authentication failure.
description: Error response when authentication fails.
controllers.ForbiddenError:
type: object
properties:
code:
type: integer
example: 403
description: HTTP status code for the error.
message:
type: string
example: forbidden
description: Human-readable description of the authorization failure.
description: Error response when the caller lacks permission.
controllers.NotFoundError:
type: object
properties:
code:
type: integer
example: 404
description: HTTP status code for the error.
message:
type: string
example: not found
description: Human-readable description of the missing resource.
description: Error response when the requested resource was not found.
controllers.InternalServerError:
type: object
properties:
code:
type: integer
example: 500
description: HTTP status code for the error.
message:
type: string
example: internal server error
description: Human-readable description of the server error.
description: Error response when the server encounters an unexpected error.
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token for the authenticated provider. Obtain this by calling
Login or Register with a valid `partner_token`. Pass the `suki_token`
value from the JSON response as the `sdp_suki_token` header on REST
requests and non-browser WebSocket upgrades. Browser WebSocket clients
pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
one hour; call Login again to refresh.
````