Dentbird OpenAPI Documentation
OpenAPI for developers
Last updated
OpenAPI for developers
Last updated
Dentbird provides an OpenAPI using an -based user authentication method. It supports 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.
The 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.
It's a RefreshToken that distinguishes users.
It's a Token that distinguishes users. When calling OpenAPI, it should be included as the following Bearer Token
The client redirects the user to the authorization server's approval endpoint.
The user approves access rights for the client.
The authentication server redirects the user to the client's redirect URI, including an authentication code.
The client requests an access token from the authentication server using the authentication code.
The authentication server issues an access token to the client.
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.
Creation of code verifier: The client first generates a random string called the code challenge (code_verifier).
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.
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.
Request for Access Token: After receiving the authorization code, the client sends the original code_verifier when requesting the access token.
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.
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.
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.
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.
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
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)
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.
code
required
Authorization code for issuing tokens
iss
required
Token Issuer
state
optional
Same value as the state value delivered on request
<Request>
<Response>
Content-Type
application/x-www-form-urlencoded
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>
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>
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
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)
The Refresh Token is a token used to obtain a new Access Token when the Access Token has expired
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.
Content-Type
application/x-www-form-urlencoded
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>
<Response>
<Body>
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>
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.
openid
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
string
OAuth 2.0 Error Field
error_description
string
OAuth 2.0 Error Field
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
This requires user scope for the user API.
Get user profile information
Authorization
string
required
Bearer <token>
This requires design-case scope for the design case API.
Authorization
string
required
Bearer <token>
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).
This API is provided only to contracted clients.
Authorization
string
required
Bearer <token>
caseId
string
required
The unique identifier of the design case.
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.
The {fileId} is responded via the 'Get Case Details' API endpoint GET /v1/design-cases/{caseId}.
Authorization
string
required
Bearer <token>
caseId
string
required
The unique identifier of case
fileId
string
required
The unique identifier of file
fileFormat
string
optional
Desired file format. Allowed values: stl, ply. Defaults to stl if omitted. Unsupported values will result in a 400 error.
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.
Authorization
string
required
Bearer <token>
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.
Authorization
string
required
Bearer <token>
Request Body should be an array and each element of the array must follow the following object format:
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.
Uploading files to the cloud uses the Azure Storage pre-signed upload URL. Upload one file for each request.
The {pre_signed_file_upload_url} is generated via the 'Register file information' API endpoint POST /v1/files.
Request URL example:
Content-Type
string
required
application/octet-stream
x-ms-blob-type
string
required
BlockBlob
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.
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.
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.
web_message: The authentication server sends the response using HTML5 Web Messaging (window.postMessage()). This method can be used in frontend applications.
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.
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.
The state parameter is used to prevent 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 is used to prevent . 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.
Clicking on the authentication link will take the end user to the Dentbird OpenAPI Log In page
After entering their Dentbird ID credentials and logging in, the user will be redirected to the OAuth consent page.
Determine the format of the result (e.g., query, fragment, form_post)
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 () using the issued
It provides
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 , requiring a process to decode them into 3D files.
