Dentbird OpenAPI Documentation

OpenAPI for developers

--- Dentbird Open API ---

Dentbird provides an OpenAPI using an Oauth2.0-based user authentication method. It supports OpenID-Connect and allows users to obtain tokens based on jwt for users through the Authorization Code method.

OpenAPI calls are made using an Access Token, and an Access Token can be issued using a Refresh Token.

Authentication

The Authorization Code is a method used to obtain access rights to the user's resources. This method involves the client obtaining an authorization code with the approval of the resource owner and obtaining an access token through it.

Refresh Token

It's a RefreshToken that distinguishes users.

Access Token

It's a Token that distinguishes users. When calling OpenAPI, it should be included as the following Bearer Token

Authentication Process

  1. The client redirects the user to the authorization server's approval endpoint.

  2. The user approves access rights for the client.

  3. The authentication server redirects the user to the client's redirect URI, including an authentication code.

  4. The client requests an access token from the authentication server using the authentication code.

  5. The authentication server issues an access token to the client.

PKCE

PKCE is a method to prevent attackers from intercepting the authentication code and obtaining an access token. The client creates a code challenge value and requests an authorization code using this value. When requesting an access token using the authorization code, the code verifier value is submitted together to verify the validity of the request by the authentication server.

Format

The code_verifier is composed of a high-entropy cryptographic random string using the characters [A-Z] / [a-z] / [0-9] / - / . / _ / . The minimum length is 43 characters, and the maximum length is 128 characters.

code-verifier = 43*128unreserved
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
ALPHA = %x41-5A / %x61-7A
DIGIT = %x30-39

How it Works

  1. Creation of code verifier: The client first generates a random string called the code challenge (code_verifier).

code_verifier = random_string_of_43_128_chars() // YtMo4nSIaf5ggWTQfh4xNRtH7PfQ1kB9LXxhIQjFna

  1. Conversion to code_challenge: The client takes the generated code_challenge, hashes it with SHA256, and then Base64 URL encodes it to produce the code_challenge. This transformation method is referred to as S256.

code_challenge = BASE64URL-ENCODE(SHA256(code_verifier)) // NwM8WVZwSBtkw--lw3u7WrOgHEA9vD1IaM-uTDm2XHg

  1. Request for Authorization Code: The client requests the authorization code, including the code_challenge. At this time, the transformation method (S256) is passed as the code_challenge_method parameter.

GET /oidc/auth
?response_type=code
&client_id=foo
&redirect_uri=https://client.example.com/callback
&scope=openid user
&code_challenge=NwM8WVZwSBtkw--lw3u7WrOgHEA9vD1IaM-uTDm2XHg
&code_challenge_method=S256

  1. Request for Access Token: After receiving the authorization code, the client sends the original code_verifier when requesting the access token.

  2. Verification: The authentication server recalculates the code_challenge using the provided code_verifier from the client and checks if it matches the code_challenge stored in the previous step. If they match, the access token is issued.

POST oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://client.example.com/callback
&client_id=foo
&client_secret=bar
&code_verifier=YtMo4nSIaf5ggWTQfh4xNRtH7PfQ1kB9LXxhIQjFna

state

The state parameter is used to prevent CSRF attacks. The client sends a random value as the state parameter during the authentication request, and the authentication server returns this value as is. The client verifies the returned value to confirm the validity of the request.

nonce

nonce is used to prevent replay attacks. The client sends a random value as the nonce parameter during the authentication request, and the authentication server includes this value in the ID token when returning it. The client verifies the nonce value of the returned ID token to confirm the validity of the request.

OpenID Connect

OpenID Connect is a user authentication protocol that extends OAuth 2.0. Through OIDC, clients can securely obtain a user's authentication status and basic profile information.

ID Token

The most important element in OIDC is the ID token. The ID token is provided in JWT (JSON Web Token) format and contains the user's authentication and profile information.

Authentication Process

Login and Authorize approve process

  1. Clicking on the authentication link will take the end user to the Dentbird OpenAPI Log In page

  2. After entering their Dentbird ID credentials and logging in, the user will be redirected to the OAuth consent page.

  3. When consent has been granted, the user will be redirected back to your callback URL (redirect_uri) with an additional query parameter that contains the authorization code, iss, and state.

Authorization Code Issuance

GET /oidc/auth

Request Query Parameters

Parameter
Required
Description

client_id

required

Client unique identifier

redirect_uri

required

URL to which the user will be redirected after authentication

scope

required

Agree items to request consent from the user

response_type

required

code (to use authorization code method)

code_challenge

required

PKCE(Proof Key for Code Exchange) is used to protect authorization codes

code_challenge_method

required

S256 (Method used to encode code_verifier for code_challenge parameter)

response_mode

optional

Determine the format of the result (e.g., query, fragment, form_post) response_mode

state

optional

The client sends an arbitrary value to the state parameter upon authentication request, which the authentication server returns. The client validates the returned value to validate the request.

nonce

optional

Included in ID tokens issued through OpenId Connect (requested only if OIDC is used)

Response

The response to the request for the authorization code is redirected with HTTP 303 and is delivered to the redirect uri via a GET request. Information such as code, iss, etc. is passed as query parameters.

Parameter
Required
Description

code

required

Authorization code for issuing tokens

iss

required

Token Issuer

state

optional

Same value as the state value delivered on request

Example

<Request>

GET /oidc/auth?client_id=foo
&redirect_uri=${REDIRECT_URI}
&scope=${SCOPE}
&response_type=code
&response_mode=query
&code_challenge_method=S256
&code_challenge=${CODE_CHALLENGE}
&state=${STATE}
&nonce=${NONCE}

<Response>

HTTP 303 Location: ${REDIRECT_URI}?code=${AUTHORIZE_CODE}&iss=https://dentbird.com

Token Issuance

POST /oidc/token

Reasons to Request Tokens from the Server

Request header

Key
Value

Content-Type

application/x-www-form-urlencoded

Request body form

Parameter
Required
Description

client_id

required

Client unique identifier

client_secret

required

Password for client

code

required

Authorization code obtained by issuing authorization code

grant_type

required

authorization_code (to use authorization code method)

redirect_uri

required

URL to which the user will be redirected after authentication

code_verifier

required

Same code verifier used to get authorization code. Required if PKCE is used for authentication code assignment requests

reponse_type

required

code

<Example>

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

code=TTgAxy9gCCOES28ZOSdah41Oi36NixtvdyY4UFtqRU3
&client_id=foo
&client_secret=bar
&grant_type=authorization_code
&redirect_uri=https://oauthdebugger.com/debug
&code_verifier=gOWfDZUsAR4sFMFIdf76hEgzTrWrsCql3wlqTtsjFZV
&reponse_type=token

Response

<Body>

Parameter
Required
Description

access_token

required

Requested Access Token

expires_in

required

Expiration date of access_token

refresh_token

required

After the access token expires, you can use it to obtain other access tokens.

id_token

optional

ID token issued through OpenIDConnect extensions, including Base64 encoded user credentials (including nonce)

scope

required

Agree items to request consent from the user

token_type

required

Bearer

<Example>

200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJqdGkiOiJVdmhHcG5GV2ppaGlUbC1OczNOQUoiLCJzdWIiOiI2NDgxOTkyMzg1YWEzM2RkYWUxM2FkMTkiLCJpYXQiOjE2OTI2NzIzMTQsImV4cCI6MTY5MjY3MjkxNCwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBjYXNlIiwiY2xpZW50X2lkIjoiZm9vIiwiaXNzIjoiaHR0cHM6Ly9kZXYtb3Blbi1hcGktc2VydmVyLmRlbnRiaXJkLmNvbSIsImF1ZCI6ImZvbyJ9.qEG3Cl7RLmZbi3Mfo4SAd1HbCUmnbW-F_ZfAb59jGX0",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InIxTGtiQm8zOTI1UmIyWkZGckt5VTNNVmV4OVQyODE3S3gwdmJpNmlfS2MifQ.eyJub25jZSI6ImZ4M3dhZWR0cXdmIiwiYXRfaGFzaCI6ImZ2QkpXZW15WmtDckVFTVE5V05GdXciLCJhdWQiOiJmb28iLCJleHAiOjE2OTI2NzU5MTQsImlhdCI6MTY5MjY3MjMxNCwiaXNzIjoiaHR0cHM6Ly9kZXYtb3Blbi1hcGktc2VydmVyLmRlbnRiaXJkLmNvbSJ9.KLVI7p5Ca3OtAyhPqs8mP0CMukg6y_XbZ3sUGJt5P-i5LoXT7Ummz6uvzDKPVcDSOjN62MlkoOn7VhzXCgcZaCWeR2u_e94wO9n2_LYosvBvdfqX449PoXKd4amhfZhd6Kx6exFBRkS_enoQYtGFiJJjo_ZipSsckzoFeatIs5J1EeJSdh4XfX3gxqwHSSEmerlDOCrSC_6viLhA8cQbT_YSUMQNpGqKuFluEoNZV4uJAPfUnab7UiK3OfETfHS4WRqbdJHIhDdzNBX4wiFlEWS8Np7l0puwEFA9xRf_h6X_7C5DCDcFMsYsKB1nq56CzaGqWd7nJaB-ZzFjjCtoRg",
  "refresh_token": "MiecFsBXRJQzU3V5WKo5aFGY2YVlBFPqsmTP7q5KoRu",
  "scope": "openid user design-case file",
  "token_type": "Bearer"
}

Tokens

ID Token

  • nonce : The nonce value passed by the client during the authentication request

  • aud : Token target (client ID)

  • exp : Token expiration time

  • iat : Token issuance time

  • iss : Token issuer

{
  "nonce": "db7412d23xe",
  "aud": "foo",
  "exp": 1695704543,
  "iat": 1695700943,
  "iss": "https://dentbird.com"
}

Access Token

The Access Token is a token used by the client to access the resource server. This token represents the permissions granted by the user to the client. You can request the Resource Server (https://open-api.dentbird.com) using the issued

  • jti : Unique token identifier

  • sub : Unique identifier of the user

  • iat : Token issuance time

  • exp : Token expiration time

  • scope : List of approved permissions

  • client_id : Client ID

  • iss : Token issuer

  • aud : Token target (client ID)

{
  "jti": "Ee69NBWduf3_G4_MypSr7",
  "sub": "64dc7e2829ecb4004dc88a5b",
  "iat": 1695608412,
  "exp": 1695694812,
  "scope": "openid user design-case file",
  "client_id": "foo",
  "iss": "https://auth-server.dev-dentbird.com",
  "aud": "foo"
}

Refresh Token

The Refresh Token is a token used to obtain a new Access Token when the Access Token has expired

Token Reissue

OAuth 2.0 provides a mechanism for users to obtain a new access token without going through the entire authentication process again. This is achieved using the refresh token.

POST /oidc/token

Request header

Key
Value

Content-Type

application/x-www-form-urlencoded

Request body form

Parameter
Description
Required

client_id

Client unique identifier

required

client_secret

Password for client

required

grant_type

refresh_token

required

refresh_token

refresh token issued

required

scope

Agree items to request consent from the user

required

<Example>

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

client_id=foo
&client_secret=bar
&grant_type=refresh_token
&refresh_token=18L9kQXGc5dPpvEtjN90lmHQxCzU4JeRiHTnKcPqJgM
&scope=openid user file design-case

<Response>

<Body>

Parameter
Required
Description

access_token

required

Requested Access Token

expires_in

required

Expiration date of access_token

refresh_token

required

After the access token expires, you can use it to obtain other access tokens.

id_token

optional

ID token issued through OpenIDConnect extensions, including Base64 encoded user credentials (including nonce)

scope

required

Agree items to request consent from the user

token_type

required

Bearer

<Example>

200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token": "eyJhbGciOiJSUzUxMiIsInR5cCI6ImF0K2p3dCIsImtpZCI6IjNCeDI2dFhlTVBxWUQ3UDNFZXRVQUo5TmY1YlZVdmpWZlQ2Q2ZraHY4ZlkifQ.eyJqdGkiOiJIY0VvRnlFalROZmpwVTlDNnlsUy0iLCJzdWIiOiI2NGRjN2UyODI5ZWNiNDAwNGRjODhhNWIiLCJpYXQiOjE2OTU3MTIxMTksImV4cCI6MTY5NTc5ODUxOSwic2NvcGUiOiJvcGVuaWQgdXNlciIsImNsaWVudF9pZCI6ImZvbyIsImlzcyI6Imh0dHBzOi8vYXV0aC1zZXJ2ZXIuZGV2LWRlbnRiaXJkLmNvbSIsImF1ZCI6ImZvbyJ9.wZLXm1LK4tcpMgu-vP7Qodvi_eCLEjzY09FreSsAysObgOQ_DInH6O3iH9ul3ByGFo5sYHuxok_9-yTUGDj1x5hOE23LHXQyF_vGwqOJjCDQ0PYoSzCnvZyVcYE4vt-8AscYc91RazkVWqqEWlXFHp-cwEXnvAjkZsX3maa8aM3QJDYfsoH4TKIgUh5ueG7DXoZzyWP20ZzlaS7BHV7Q1zGWA-YCZzKkPZdfrzmu7yC77Knj_W8LN5137BhX7hYhIQ653ajds6UnkjU_hGPkzO3KZ1Qx80BeVlD20MQX6lsAyw96ReBYYly0FmXHajubto_e3EarOx1l5tx6aL4AjSKH4VPu2zehVyC6fgFA5sfzTFZJjvQ4UTvlZEVuVlbU7thjjxU_Y9AebF8At7sQoU4odUzGbuTOLQthN3Eef4owNcb1AZnq_FCFIsj8br1_zcqmCNz9iyoa5cdPmeYIZURubjMQSqVAWj0hDOjQUcRTvfA3suPj_UgPQQUV1gu0",
    "expires_in": 86400,
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNCeDI2dFhlTVBxWUQ3UDNFZXRVQUo5TmY1YlZVdmpWZlQ2Q2ZraHY4ZlkifQ.eyJzdWIiOiI2NGRjN2UyODI5ZWNiNDAwNGRjODhhNWIiLCJub25jZSI6IjVyZDl5d2xudjdoIiwiYXRfaGFzaCI6IlprTlN5dENnbk5pWGs2dkZ3R2RwQUEiLCJhdWQiOiJmb28iLCJleHAiOjE2OTU3MTU3MTksImlhdCI6MTY5NTcxMjExOSwiaXNzIjoiaHR0cHM6Ly9hdXRoLXNlcnZlci5kZXYtZGVudGJpcmQuY29tIn0.lf3yIYJfERuvWKQ9ojUGrUWz1pmoQCMOv4ajrYfxP-TWDjMg6Br2mmIJAytWbfeeXnApwy8TJ5G_xSEJKL6_w_mHVxL_FGr7LDNLSXsP8gB5-752m4wldCHvpNn32wqUc5e4OeNkmv5GqZkdW7hKPDPJgz_jCU5QIfIAPbN-FbOt3KiH26DtYImtsrAJSCXcpWiK3s8m9HCOk5nDoNFWADHtwORiKsBrt00BGgCNbdL38iSM6S8jB1ZQszW3HNpONNtC9IvZGtjlQPc_XFV3CKHOymTRRXdnI-SLYRevBJ-2nG5VfCEfCBwP53vXzeb2aVikhHMpKKWFsNdor1ZcodborWeWJoBR9DJt5WLEhZs3Ey3Zflaxybt8pY5-h4jg42mYGMkq1592zZ9H8KasNEtyXTtjopGW-aDM9Qt6T4Xd2zYbK_W-7FMYRAbUvPx8HxLKOFHXhfe5Vxeqn3ALFspeJ07TSauRZLtbwOhQhqMnENUVnV1xxbGWQkVLfQd7",
    "refresh_token": "WdcTGy80sF789exbXiVMhiufuPTqMMFHuvIVY0SBk-T",
    "scope": "openid user design-case file",
    "token_type": "Bearer"
}

Scopes

A Scope is a string identifier used by the client to specify the range or permissions for accessing resources from a user's account. The Scope clearly informs the user about which data access permissions are being requested.

Scope
Description

openid

It providesDentbird OpenAPI Documentation

user

You can read user profile information

design-case

You can read, create, and delete design-case information

file

You can read, download, upload, and delete files

Error Code Format

OAuth Authentication APIs Error Code

interface AuthenticationErrorResponse {
  error: string;
  error_description: string;
}
Field
Type
Description

error

string

OAuth 2.0 Error Field

error_description

string

OAuth 2.0 Error Field

Resource APIs Error Code

interface ErrorResponse {
  timestamp: ISODate;
  success: false;
  errorCode: string;
  message: string;
}
Field
Type
Description

timestamp

ISO Date

yyyy-MM-dd'T'hh:mm:ss.SSSSSSZ

success

boolean

API Success or Faield boolean value

errorCode

string

API Error Code

message

string

API Error Message

--- Resource APIs ---

User

This requires user scope for the user API.

Get User Info

Get user profile information

GET /v1/users/me

Request headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Response body structure

{
  "email": "gildong@imagoworks.ai",
  "firstName": "Gildong",
  "lastName": "Hong",
  "profileImage": "https://dev-cloud-cdn.dentbird.com/public/profileImage/avalatte30@imagoworks.ai/ec5e20be-3675-4354-876c-78a48a8eda1c.png",
  "occupation": "Dentist"
}

Design-Case

This requires design-case scope for the design case API.

Get Case List

GET /v1/design-cases

Request headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Request query parameter

Parameter
Type
Constraints
Description

lifecycle

string

optional

Filter design cases based on lifecycle status.

  • CREATED: Newly created design cases.

  • TRASHED: Design cases moved to the trash.

  • DELETED: Permanently deleted design cases.

status

string

optional

Filter design cases based on status type.

  • CREATED: Design cases that are newly created.

  • DESIGNED: Design cases that have been designed.

  • CAM: Design cases that are in the CAM (Computer-Aided Manufacturing) stage.

caseName

string

optional

Filter design cases by case name using a partial match (LIKE search).

referenceId

string

optional

Filter design cases by reference ID using an exact match.

page

number

required

Specifies the page number for pagination (1-based index, where the first page is 1).

Response body structure

{
    "success": true,
    "data": {
        "items": [
            {
                "designCaseId": "20221103-000034",
                "createAt": "2022-11-03T07:51:39.420Z",
                "lifecycle": "TRASHED",
                "status": "DESIGNED",
                "caseName": "Sample Case 1 - Designed Crown",
                "updateAt": "2022-11-03T07:51:39.420Z",
                "isFlagged": false,
                "patientId": "",
                "importPlatform": "Dentbird",
                "projectType": "CROWN"
            },
            {
                "designCaseId": "20220908-000001",
                "createAt": "2022-09-08T01:25:20.990Z",
                "lifecycle": "TRASHED",
                "status": "DESIGNED",
                "caseName": "Sample Case 1 - Designed Crown",
                "updateAt": "2022-09-08T01:25:20.990Z",
                "isFlagged": false,
                "patientId": "",
                "importPlatform": "Dentbird",
                "projectType": "CROWN"
            }
        ],
        "totalCount": 2,
        "page": 1,
        "totalPage": 1,
        "count": 2,
        "hasNext": false,
        "hasPrev": false,
        "isFirst": true,
        "isLast": true
    }
}

Get Case Details

This API is provided only to contracted clients.

GET /v1/design-cases/{caseId}

Retrieves the details of a specific design case identified by designCaseId. The designCaseId can be obtained from the Get Case List API. The response includes comprehensive information about the design case, such as lifecycle status, case information, and associated mesh files. Note that the mesh blob files are compressed using the Draco library, requiring a process to decode them into 3D files.

Reqeust headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Request path parameter

Parameter
Type
Constraints
Description

caseId

string

required

The unique identifier of the design case.

Response body structure

{
    "success": true,
    "data": {
        "crownProjectType": "CROWN",
        "caseInfo": {
            "designCaseId": "20240605-260104",
            "createAt": "2024-06-05T08:25:08.390Z",
            "lifecycle": "CREATED",
            "status": "DESIGNED",
            "caseName": "untitled design case",
            "updateAt": "2024-06-05T08:30:42.896Z",
            "isFlagged": false,
            "patientId": "",
            "importPlatform": "Dentbird",
            "projectType": "CROWN"
        },
        "scanMeshList": [
            {
                "groupType": "0",
                "modelType": "upperBase",
                "meshFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "ARCH/UPPER_BASE/default.drc.gz",
                    "fileId": "66602231f565f7196cb55afc"
                },
                "thumbnailFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "thumbnail.png",
                    "fileId": "66602231f565f7196cb55b02"
                },
                "textureFiles": [
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "ARCH/UPPER_BASE/default.drc.gz",
                        "fileId": "66602231f565f7196cb55afc"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "thumbnail.png",
                        "fileId": "66602231f565f7196cb55b02"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "ARCH/LOWER_BASE/default.drc.gz",
                        "fileId": "66602231f565f7196cb55b0a"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "thumbnail.png",
                        "fileId": "66602231f565f7196cb55b10"
                    }
                ]
            },
            {
                "groupType": "1",
                "modelType": "lowerBase",
                "meshFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "ARCH/LOWER_BASE/default.drc.gz",
                    "fileId": "66602231f565f7196cb55b0a"
                },
                "thumbnailFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "thumbnail.png",
                    "fileId": "66602231f565f7196cb55b10"
                },
                "textureFiles": [
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "ARCH/UPPER_BASE/default.drc.gz",
                        "fileId": "66602231f565f7196cb55afc"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "thumbnail.png",
                        "fileId": "66602231f565f7196cb55b02"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "ARCH/LOWER_BASE/default.drc.gz",
                        "fileId": "66602231f565f7196cb55b0a"
                    },
                    {
                        "downloadUrl": "<downloadUrl>",
                        "fileName": "thumbnail.png",
                        "fileId": "66602231f565f7196cb55b10"
                    }
                ]
            }
        ],
        "meshList": [
            {
                "modelType": "crown",
                "toothNumber": 36,
                "meshFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "CROWN/CROWN/default.drc.gz",
                    "fileId": "66602231f565f7196cb55af2"
                },
                "thumbnailFile": {
                    "downloadUrl": "<downloadUrl>",
                    "fileName": "thumbnail.png",
                    "fileId": "66602231f565f7196cb55afe"
                }
            }
        ]
    }
}

Download file

This API is provided only to contracted clients.

This API is provided only to contracted clients. Files are downloaded directly from the Dentbird server. When downloading a mesh-type file, you can specify the desired format as either PLY or STL. If no format is specified, the file will be downloaded in STL format by default.

Resource Information

GET /v1/design-cases/{caseId}/download-file/{fileId}

The {fileId} is responded via the 'Get Case Details' API endpoint GET /v1/design-cases/{caseId}.

Reqeust headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Request path parameter

Parameter
Type
Constraints
Description

caseId

string

required

The unique identifier of case

fileId

string

required

The unique identifier of file

Request query parameter

Parameter
Type
Constraints
Description

fileFormat

string

optional

Desired file format. Allowed values: stl, ply. Defaults to stl if omitted. Unsupported values will result in a 400 error.

Response body

{file_content_as_raw}

Transfer data to Dentbird Solution

This API processes the client's uploaded data for use with Dentbird solutions.

Before calling this API, you must register the information of the files to be uploaded using the 'Register file information' API(POST /v1/files/upload), and subsequently upload the files via the Azure Storage pre-signed upload URL.

POST /v1/design-cases/transfer

Request headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Request body form

Parameter
type
Constraints
Description

caseName

string

required

case name

projectType

string

required

Currently, only 'CROWN' is supported.

fileIds

string[]

required

The set of file Ids generated from the 'Register file information' API.

referenceId

string

required

It refers to the reference ID, which can be utilized subsequently for case tracking.

Request body example

{
  "caseName": "untitled design case",
  "projectType": "CROWN",
  "fileIds": ["6512622222e0e4424b5dfe89", "BB46A43275248F9131DB0F9729AC6AD4"],
  "referenceId": "<your_reference_id>"
}

Response body sturcture

{
  "success": true,
  "data": {
    "redirectUrl": "<redirect_url>"
  }
}

File

Register file information 

POST /v1/files

Request headers

Name
Type
Constraints
Description

Authorization

string

required

Bearer <token>

Request body form

Request Body should be an array and each element of the array must follow the following object format:

Parameter
type
Description

fileName

string

file name

contentLength

number

file byte size

contentMD5

string

Provide the Content-MD5 value of your file, encoded in Base64 format.

category

string

It refers to the 'upload file' category. Currently, only 'CASE_INPUT' is supported.

Request body example 

[
  {
    "fileName": "lower.ply",
    "contentLength": 12345,
    "contentMD5": "kS7IA7LOSeSlQQaNSVq1cA==",
    "category": "CASE_INPUT"
  },
  {
    "fileName": "upper.ply",
    "contentLength": 54321,
    "contentMD5": "u0akMnUkj5Ex2w+XKaxq1A==",
    "category": "CASE_INPUT"
  }
]

Response status

201 Created

Response body structure

{
  "success": true,
  "data": [
    {
      "fileName": "mx.ply",
      "uploadUrl": "<pre_signed_file_upload_url>",
      "fileId": "6512622222e0e4424b5dfe89"
    },
    {
      "fileName": "mn.ply",
      "uploadUrl": "<pre_signed_file_upload_url>",
      "fileId": "6512622222e0e4424b5dfe8a"
    }
  ]
}

Upload file

Uploading files to the cloud uses the Azure Storage pre-signed upload URL. Upload one file for each request.

Resource Information

PUT {pre_signed_file_upload_url}

The {pre_signed_file_upload_url} is generated via the 'Register file information' API endpoint POST /v1/files.

Request URL example:

{baseUrl}/users/640ef030b81817c032c85beb/cases/input/0de4c00b-a8fc-4692-9113-66e48aad813f.ply?sv=2022-11-02&spr=https&st=2024-03-15T02:11:23Z&se=2024-03-15T02:26:23Z&sr=b&sp=w&sig=652sgqHr05B41WMkzQ0wpxatQkWV1rV1Nirwf3RgbZA=

Request headers

Name
Type
Constraints
Description

Content-Type

string

required

application/octet-stream

x-ms-blob-type

string

required

BlockBlob

Request body form

{file_content_as_raw}

Response status

201 Created

Appendix

response_mode

response_mode is a parameter in OpenID Connect (OIDC) and OAuth 2.0 that specifies how the client will receive a response from the authentication server. This parameter allows the client to have more granular control over how it receives the response.

  • query: The authentication server includes the response in the query string of the client's redirection URI. This is the default and is used in most of the authorization code flows.

303 See Other
Location: https://client.example.com/callback
?code=LqhwVE1Upzt6sU0CEQ-zqWrFjm70wa5UCEN_A5QruQP
&state=n61p3c05rpk
&iss=https://auth-server.dev-dentbird.com

  • fragment: The authentication server includes the response in the fragment (the part after #) of the client's redirection URI. This is mainly used in the implicit flow.

303 See Other
Location: https://client.example.com/callback
#code=LqhwVE1Upzt6sU0CEQ-zqWrFjm70wa5UCEN_A5QruQP
&state=n61p3c05rpk
&iss=https://auth-server.dev-dentbird.com

  • form_post: The authentication server sends the response to the client's Redirect URI using HTTP POST. This method is useful for transmitting the response without exposing sensitive information through the browser.

200 OK
Content-Type: text/html

<html>
<body>
<form method="post" action="https://client.example.com/callback">
  <input type="hidden" name="code" value="AUTH_CODE"/>
  <input type="submit" value="Submit"/>
</form>
<script>document.forms[0].submit();</script>
</body>
</html>

  • web_message: The authentication server sends the response using HTML5 Web Messaging (window.postMessage()). This method can be used in frontend applications.

200 OK
Content-Type: text/html

<html>
<body>
<script>
  window.opener.postMessage({ code: "AUTH_CODE" }, "https://client.example.com");
</script>
</body>
</html>

Reasons to Request Tokens from the Server

When implementing OAuth 2.0 or OpenID Connect, it's important to understand where and how to request token issuance. While it's technically possible to request tokens directly from client-side applications like browser-based SPAs, there are important security considerations to keep in mind.

  • Protecting the Client Secret : In the OAuth 2.0 authorization code flow, the Client Secret is used to authenticate the client application to the authentication server. If the token request is made directly from the client side, there's a risk of exposing the Client Secret. Server-side calls can securely store and use the client secret without exposing it to the end user or potential attackers.

  • CSRF : Making the token request from the server side provides better mechanisms to prevent CSRF attacks. The server can implement CSRF prevention tokens and other measures more effectively than client-side applications.

  • Token Storage : Access tokens, refresh tokens, and ID tokens should be stored securely. Storing tokens directly in client-side storage mechanisms (e.g., local storage) exposes them to theft through XSS attacks. On the server side, tokens can be securely stored in server-side sessions or other secure storage mechanisms.

  • Preventing Token Leakage : If client-side applications interact directly with the authentication server, tokens can leak through browser history, logs, or referrer headers. Server-side implementations can prevent such leaks.

  • Logging and Monitoring : Token requests and responses can be logged more effectively through server-side implementations. This can be crucial for auditing, monitoring, and detecting potential security threats.

  • Network Security : In a server-side environment, advanced network security measures such as secure VPNs, firewalls, and encrypted traffic can be implemented. This might be more challenging to enforce in client-side applications.

  • CORS

    • Browser Restrictions : Browsers restrict web pages from making requests to a domain other than the one that served the web page, a policy known as the "same-origin policy". If a client-side application tries to directly request a token from an authentication server of a different origin, it becomes a cross-origin request. If the authentication server doesn't set the appropriate CORS headers, the browser will block the request.

    • Exposure of Sensitive Operations : Even if the authentication server is configured to support CORS, making a direct token request from the client side exposes sensitive operations to the less secure browser environment. This increases the risk of man-in-the-middle attacks, token leakage, or other vulnerabilities.

    • Preflight Overhead : For certain types of requests, browsers perform a CORS preflight, an additional request to check if the cross-origin request is safe. This adds overhead and complexity to the process.

While client-side token requests might seem simpler and more direct, they come with significant potential security risks. For robust security, it's advisable to handle token issuance on the server side, ensuring that sensitive credentials, tokens, and other critical information are protected from exposure and potential attacks.

By handling token issuance on the server side and considering CORS, developers can ensure a more secure and reliable authentication and authorization process, protecting both end users and the resources they access.

Last updated