Find API Calls

Calls to the Find API are direct and don't use a proxy system like SmartThings.

Note: Most API calls are currently not documented as uTag does not use them. The Find API appears to be in its infancy and is missing important pieces of functionality, like accessing shared Tag locations. When this gets added, or if uTag adds support for other APIs, they will be documented here.

Get PIN

Get the E2E pin for the current user

Request

GET https://api.samsungfind.com/users/{id}/key

Where ID is the user's ID, which is provided during the authentication process.

Headers

Key	Type	Value
X-Sec-Sa-Userid	String	The user's ID
X-Sec-Sa-Countrycode	String	The user's ISO 3166-1 alpha-3 country code
X-Sec-Sa-Authserverurl	String	The auth server URL, provided during authentication
X-Sec-Sa-Authtoken	String	Auth token for Find API
X-Sec-Tab-Name	String	DEVICES

Response

Key	Type	Value
requestId	String	Unique ID for this request
timeCurrent	Long	Server timestamp
item	Object	Actual response, or null if no key is set

Response object

Key	Type	Value
privateKey	String	Base64 encoded private key
publicKey	String	Base64 encoded public key
iv	String	Base64 encoded IV
timeUpdated	Long	Unix timestamp of when the key was set

Set PIN

Set or update the E2E PIN for the current user. This applies across all Tags.

Request

PUT https://api.samsungfind.com/users/{id}/key

Where ID is the user's ID, which is provided during the authentication process.

Headers

Key	Type	Value
X-Sec-Sa-Userid	String	The user's ID
X-Sec-Sa-Countrycode	String	The user's ISO 3166-1 alpha-3 country code
X-Sec-Sa-Authserverurl	String	The auth server URL, provided during authentication
X-Sec-Sa-Authtoken	String	Auth token for Find API
X-Sec-Tab-Name	String	DEVICES

Request Body

application/json

Key	Type	Value
item	Object	Actual request data object

Request Object

Key	Type	Value
privateKey	String	Base64 encoded private key
publicKey	String	Base64 encoded public key
iv	String	Base64 encoded IV

Generating a key

• Take the user's desired PIN, and append the user ID to the end of it
• Generate a keypair with the EC algorithm
• Generate a 16 byte IV
• Generate an AES key with the transformation AES/CBC/PKCS5Padding, using the SHA-256 hash of the combined PIN and user ID as the key and the IV from above
• Encrypt the generated private key with this AES key
• Encode the encrypted private key in base64 and append _v2 to the end of it
• Base64 encode the IV & public key, then send to the server