It doesn’t have to be perfect. Build your mini app for a chance to win up to KRW 3 million.
Ctrlk
SupportCommunityConsole
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Toss Authentication

Set up a Toss authentication contract >

This explains how to contract for using the Toss authentication service.

Please check the minimum version

  • SDK : 1.2.1 or later

  • Toss app (identity verification) : 5.233.0 or later

  • Toss app (one-touch authentication) : 5.236.0 or later

Use the getTossAppVersion function to check the Toss app version.

Firewall settings

On the request server's outbound (Outbound) settings, allow the Toss authentication IP below. All communication is port 443 (HTTPS) is used.

The Toss authentication server has inbound (Inbound) open without restrictions, so you can communicate right away without any separate settings.

Identity verification IP

  • 117.52.3.222

  • 117.52.3.235

  • 211.115.96.222

  • 211.115.96.235

1. Get Access Token

For Toss identity verification, Access Tokenissue an Access Token. The issued token will be used in the Authorization headers of all subsequent API calls.

The token has expiration time (expires_in) it. When it expires, you must issue a new token, and if a valid token exists, avoid reissuing it to reduce unnecessary calls.

  • Base URL: https://oauth2.cert.toss.im

  • Endpoint: /token

  • Method: POST

  • Content-Type: application/x-www-form-urlencoded

Request headers

Name
Type
Whether required
Description

Content-Type

string

Y

application/x-www-form-urlencoded

Request parameters

Name
Type
Whether required
Description

grant_type

string

Y

fixed value: client_credentials

scope

string

Y

authentication request scope (e.g., ca)

client_id

string

Y

client ID issued to the customer

client_secret

string

Y

client secret issued to the customer

Response

Name
Type
Description

access_token

string

Access Token value

scope

string

issued authentication scope

token_type

string

Token type (always Bearer)

expires_in

number

Token expiration time (in seconds)

2. Request authentication

On the Toss authentication server, txIdissue a txId and start the identity verification process.

  • BaseURL : https://cert.toss.im

  • Endpoint : /api/v2/sign/user/auth/request

  • Method : POST

  • Content-type : application/json

2-1. Personal information-based authentication

The customer's name, date of birth, and phone number the sent after encryptionThis is how it works. For security, the session key (sessionKey)must be newly generated for each request.

Request headers

Name
Type
Whether required
Description

Authorization

string

Y

Bearer {Access Token}

Content-Type

string

Y

application/json

Request parameters

Name
Type
Whether required
Description

requestUrl

string

Y

The customer app scheme to return to when using Toss identity verification

requestType

string

Y

USER_PERSONAL

triggerType

string

Y

APP_SCHEME

userName

string

Y

Encryption Required

userPhone

string

Y

digits only, Encryption Required

userBirthday

string

Y

YYYYMMDD, Encryption Required

sessionKey

string

Y

For AES encryption/decryption, a new one must be generated for each request (How to generate)

Request example

Response example

Success response

Name
Type
Description

resultType

string

Request result (success: SUCCESS, failure: FAIL)

success.txId

string

A value that uniquely identifies the transaction as the authentication request transaction ID. Since it uniquely identifies a specific transaction, you must store and manage it.

success.requestedDt

string

Initial request time (YYYY-MM-DDThh:mm:ss±hh:mm)

success.appScheme

string

App scheme information that can open the Toss authentication screen

success.androidAppUri

string

It works like appScheme as the authentication app scheme value for Android, but because it uses Chrome Intent, it has the advantage of being able to determine whether the Toss app is installed without any additional implementation on the customer's side.

success.iosAppUri

string

It works like appScheme as the authentication app scheme value for iOS, but because it uses Universal Link, it has the advantage of being able to determine whether the Toss app is installed without any additional implementation on the customer's side, just like on Android.

Failure response

Name
Type
Description

resultType

string

If it fails, FAIL

error.errorType

number

Error type

error.errorCode

string

Error code (e.g., CE1000)

error.reason

string

Error message

error.data

object

Additional data (if any)

error.title

string | null

Error title (if any)

Next step

In the response, txIdUsing appsInTossSignTossCert calling the function will open the Toss app authentication screen. Open the authentication screenplease refer to.

2-2. One-touch authentication

On the client, without entering personal information call the Toss app and complete authentication in one go.

Request headers

Name
Type
Required
Description

Authorization

string

Y

Bearer {Access Token}

Content-Type

string

Y

application/json

Request parameters

Name
Type
Required
Description

requestType

string

Y

"USER_NONE"

requestUrl

string

Y

The app scheme to return to after authentication is complete

Request example

Response example

Success response

Name
Type
Description

resultType

string

Request result (success: SUCCESS, failure: FAIL)

success.txId

string

A value that uniquely identifies the transaction as the authentication request transaction ID. Since it uniquely identifies a specific transaction, you must store and manage it.

success.requestedDt

string

Initial request time (YYYY-MM-DDThh:mm:ss±hh:mm)

Failure response

Name
Type
Description

resultType

string

If it fails, FAIL

error.errorType

number

Error type

error.errorCode

string

Error code (e.g., CE1000)

error.reason

string

Error message

error.data

object

Additional data (if any)

error.title

string | null

Error title (if any)

Next step

In the response, txIdUsing appsInTossSignTossCert calling the function will open the Toss app authentication screen. Open the authentication screenplease refer to.

3. Open the authentication screen

Included in the identity verification request API response txIdincluding appsInTossSignTossCertcalling it will open the Toss app authentication screen.

One-touch authentication and app version guide

When using the one-touch authentication method (USER_NONE) , skipConfirmDocthe truesetting it to true allows you to skip the certificate confirmation document step.

  • Toss authentication (requestType: USER_PERSONAL): Toss app 5.233.0 or later

  • Toss one-touch authentication (requestType: USER_NONE): Toss app 5.236.0 or later

Use the getTossAppVersion function to check the Toss app version.

Response

  • onSuccess

    • No parameters

  • onError

    • Error { code: string; message: string } (e.g., user cancellation, app not installed, scheme failure, etc.)

4. Check identity verification status

User's current authentication progress statusis retrieved. txIdUse it to check the current authentication stage (REQUESTED, IN_PROGRESS, COMPLETED, EXPIRED).

Please note

The status lookup API is for checking progress status. The final authentication success status should be determined by the results lookup API.

  • BaseURL : https://cert.toss.im

  • Endpoint : /api/v2/sign/user/auth/id/status

  • Method : POST

  • Content-type : application/json

Request headers

Name
Type
Whether required
Description

Authorization

string

Y

Bearer {Access Token}

Content-Type

string

Y

application/json

Request parameters

Name
Type
Whether required
Description

txId

string

Y

Authentication request transaction ID that needs status checking

Request example

Success response

Name
Type
Description

resultType

string

Request result. On success SUCCESS

success.txId

string

Retrieved authentication transaction ID

success.status

string

Authentication progress status (see the "status values" table below)

success.requestedDt

string

Initial authentication request time (YYYY-MM-DDThh:mm:ss±hh:mm, ISO 8601)

Failure response

Name
Type
Description

resultType

string

If it fails, FAIL

error.errorType

number

Error type

error.errorCode

string

Error code (e.g., CE3100)

error.reason

string

Error message

error.data

object

Additional data (if any)

error.title

string | null

Error title (if any)

status values

Value
Description

REQUESTED

A state in which authentication has been requested from the Toss authentication server to the user's Toss app

IN_PROGRESS

The user is in the process of authenticating

COMPLETED

The customer has completed authentication (The final determination should be made using the results lookup API)

EXPIRED

Authentication cannot proceed because the validity period has expired

5. Check identity verification results

For a user whose authentication is complete, result informationis retrieved. Retrieval must be done via server-to-server communicationPlease proceed through it. Information collected from identity verification results should be stored safely on the server, and later compared and verified with that information during electronic signature/simple authentication.

Please note

For the results lookup API, based on success up to 2 timesYou can only look it up up to that point. After completing user authentication Within 60 minutes (1 hour) You must finish checking the result. If it exceeds 60 minutes, result lookup will be limited and you must start again from the certification request API.

  • BaseURL : https://cert.toss.im

  • Endpoint : /api/v2/sign/user/auth/id/result

  • Method : POST

  • Content-type : application/json

Request headers

Name
Type
Whether required
Description

Authorization

string

Y

Bearer {Access Token}

Content-Type

string

Y

application/json

Request parameters

Name
Type
Whether required
Description

txId

string

Y

Transaction ID of the certification request whose result needs to be checked

sessionKey

string

Y

In result lookup, regardless of the authentication method txIdMust be sent together with it. Session key for AES encryption/decryption of requests/responses; create a new one for each request and do not reuse the session key used in the authentication request (How to generate)

Request example

Success response

Name
Type
Description

resultType

string

On success SUCCESS

success.txId

string

Certification transaction ID whose result was looked up

success.status

string

COMPLETED (Result lookup completed successfully)

success.userIdentifier

string | null

Not used in the current version (null)

success.userCiToken

string | null

Not used in the current version (null)

success.signature

string

Electronically signed value signed by the user (Base64-encoded DER). Must be stored and managed together with txId

success.randomValue

string | null

Not used in the current version (null)

success.completedDt

string

Time when user authentication was completed (YYYY-MM-DDThh:mm:ss±hh:mm, ISO 8601)

success.requestedDt

string

Initial authentication request time (YYYY-MM-DDThh:mm:ss±hh:mm, ISO 8601)

success.personalData

object

Used for authentication Personal information (encrypted value). See the subfield table below.

personalData (user personal information used for authentication) Object

Name
Type
Description

ci

string

Encrypted user's CI

name

string

Encrypted user's name

birthday

string

Encrypted 8-digit birth date

gender

string

Encrypted gender information (MALE | FEMALE)

nationality

string

Encrypted nationality (LOCAL | FOREIGNER)

ci2

string | null

Temporary parameter for handling CI leakage in unpredictable situations, null Fixed

di

string

Encrypted user's DI

ciUpdate

string | null

Temporary parameter for handling CI leakage in unpredictable situations, null Fixed

ageGroup

string

Encrypted adult/minor status (ADULT | MINOR)

Failure response

Name
Type
Description

resultType

string

If it fails, FAIL

error.errorType

number

Error type

error.errorCode

string

Error code (e.g., CE3102)

error.reason

string

Error message

error.data

object

Additional data (if any)

error.title

string | null

Error title (if any)

Test

Even if the contract has not been completed Toss authentication test environmentyou can try integrating it. Please complete the integration first, then run the test. When testing, the latest version of the Toss app installed from the app storeplease use it. Identity verificationand One-touch authentication Both methods can be tested.

Test environment credentials

  • client_id : test_a8e23336d673ca70922b485fe806eb2d

  • client_secret : test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3

Differences from the live environment

Authentication is free — You will not be charged even if authentication completes successfully.

Test environment credentials — client_id, client_secret All test_ It starts with test_. This prefix makes it easy to distinguish it from production environment information.

Access Token validity period — For integration convenience 1 year (31,536,000 seconds) An expiration period is applied. In the production environment, it may vary depending on the network method applied for by the business.

Provision of virtual personal information — Instead of the encrypted personal information of a user registered with Toss the fixed personal information of a virtual person created by Tossis provided. This is a measure to protect real user information, and if you need accurate user information, the institution-specific key provided by Tossmust be used to integrate with the production environment.

Examples of virtual personal information provided in the test environment

  • CI : CI0110000000001 ...

  • DI : DI0110000000001 ...

  • Name : Kim Toss

  • Date of birth : 19930324

  • Gender : FEMALE

  • Local/foreigner status : LOCAL

Generating a session key

For security, the session key (sessionKey) must be newly generated for each request.

For a more detailed example, herecheck it out.

Personal information encryption/decryption

The Toss certification API may include customer personal information in some requests. For safety, the customer server and the Toss server exchange only encrypted data. If plain text is needed, decrypt the data to check it.

  • Encrypt when sending the customer's name, date of birth, and mobile phone number in a certification request

  • Encrypt the original text if the original text of the electronic signature service contains the customer's personal information

  • Encrypt when the Toss server provides personal information including CI and DI as a certification result

One-touch identity verification

Because the customer's information is not transmitted from the client server to the Toss Certification server, encryption is unnecessary. However, when you call the result lookup API after user authentication is complete, you must include the session key in the request.

Session key generation and encryption example

See

In the Toss test environment, it provides fixed personal information for a virtual person created by Toss, not the real user's personal information.

Public key used when generating the session key

By default, using the SDK is recommended, but code samples in various languages are also provided. For a detailed example, herecheck it out.

PreviousToss Login
NextUser Information

Last updated

Was this helpful?