Exchange a one-time SSO code for the identity
curl --request POST \
--url https://api.pid.peridotvault.com/v1/auth/exchange \
--header 'Content-Type: application/json' \
--data '
{
"code": "mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH",
"clientId": "pidapp_0123456789abcdef0123456789abcdef"
}
'const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
code: 'mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH',
clientId: 'pidapp_0123456789abcdef0123456789abcdef'
})
};
fetch('https://api.pid.peridotvault.com/v1/auth/exchange', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.pid.peridotvault.com/v1/auth/exchange"
payload = {
"code": "mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH",
"clientId": "pidapp_0123456789abcdef0123456789abcdef"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pid.peridotvault.com/v1/auth/exchange"
payload := strings.NewReader("{\n \"code\": \"mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH\",\n \"clientId\": \"pidapp_0123456789abcdef0123456789abcdef\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"pid": "ifal@pid",
"identityId": "ifal@pid",
"profile": {
"displayName": "<string>",
"avatarUrl": "<string>"
},
"credentials": [
{
"provider": "<string>",
"email": "<string>"
}
]
}{
"statusCode": 400,
"message": [
"handle must be 3-20 chars: lowercase letters, numbers, underscore"
]
}{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}auth
Exchange a one-time SSO code for the identity
Consumes a pid_code issued by a Google or passkey login with returnTo
(optionally bound to a clientId) and returns the PeridotID identity.
Codes are single-use and expire after ~5 minutes. Call server-to-server;
when the code is bound to an app, the same clientId must be presented.
POST
/
auth
/
exchange
Exchange a one-time SSO code for the identity
curl --request POST \
--url https://api.pid.peridotvault.com/v1/auth/exchange \
--header 'Content-Type: application/json' \
--data '
{
"code": "mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH",
"clientId": "pidapp_0123456789abcdef0123456789abcdef"
}
'const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
code: 'mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH',
clientId: 'pidapp_0123456789abcdef0123456789abcdef'
})
};
fetch('https://api.pid.peridotvault.com/v1/auth/exchange', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.pid.peridotvault.com/v1/auth/exchange"
payload = {
"code": "mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH",
"clientId": "pidapp_0123456789abcdef0123456789abcdef"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pid.peridotvault.com/v1/auth/exchange"
payload := strings.NewReader("{\n \"code\": \"mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH\",\n \"clientId\": \"pidapp_0123456789abcdef0123456789abcdef\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"pid": "ifal@pid",
"identityId": "ifal@pid",
"profile": {
"displayName": "<string>",
"avatarUrl": "<string>"
},
"credentials": [
{
"provider": "<string>",
"email": "<string>"
}
]
}{
"statusCode": 400,
"message": [
"handle must be 3-20 chars: lowercase letters, numbers, underscore"
]
}{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}Body
application/json
Response
The PeridotID identity behind the code
Permanent PID of the signed-in user (treat as opaque)
Pattern:
^[a-z0-9_]{3,20}@pid$Example:
"ifal@pid"
Shim — identical to pid, removed next release
Example:
"ifal@pid"
Show child attributes
Show child attributes
Show child attributes
Show child attributes