StampMitra B2B API हर request को API key से authenticate करती है। Keys environment के हिसाब से अलग होती हैं और उनके scopes तय करते हैं कि कौन-सा endpoint चल सकता है।
Sandbox keys का prefix sk_test_ होता है और production keys का sk_live_। Sandbox key self-signup से तुरंत मिल जाती है; production keys के लिए KYC-approved organization होना ज़रूरी है।
अपनी key भेजना
Authorization header
Authorization: Bearer sk_test_xxxxxxxxxxxx
# या
x-api-key: sk_test_xxxxxxxxxxxx
API Key Authentication
Bearer API key + scopes
Endpoint
GET (applies to every /v1/* endpoint)
GET(applies to every /v1/* endpoint)लाइव
हर protected endpoint के लिए Authorization: Bearer <key> या x-api-key: <key> header ज़रूरी है। Keys environment-scoped होती हैं (SANDBOX sk_test_... बनाम PRODUCTION sk_live_...) और उनमें OAuth-style scopes की सूची होती है (जैसे verification.pan.read, orders.create, payments.write)। संवेदनशील scopes को IP allowlist तक भी सीमित किया जा सकता है। Requests पर server-side per-endpoint rate limits भी लागू होती हैं।
उदाहरण
Call करके देखें
curl -X GET "https://api-b2b.stampmitra.in(applies to every /v1/* endpoint)" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxx"
Playground
Try करें
यह endpoint planned है और अभी इसका backend नहीं है, इसलिए call नहीं हो सकता।
Dashboard Login (Email + Password + OTP)
Dashboard user sign up करें (email + password)
Endpoint
POST /v1/auth/password/signup
POST/v1/auth/password/signupलाइव
एक Organization बनाता है (या किसी में join नहीं करता - organizationName वैकल्पिक है और न देने पर personal workspace अपने-आप बन जाता है) और bcrypt-hashed password के साथ owner User बनाता है। अभी कोई session set नहीं होता; verification email भेजा जाता है। Per-IP और per-email rate-limited है।
Request
Request के parameters
Request के parameters
Field
Type
विवरण
fullNameज़रूरी
string
1-150 characters।
emailज़रूरी
string
Valid email address।
passwordज़रूरी
string
10-72 chars; upper, lower, digit और symbol ज़रूर हों।
organizationName
string
अधिकतम 200 characters। छोड़ देने पर personal workspace अपने-आप बनता है।
{
"organizationId": "org_5f2c1a9b3d7e4f6a",
"userId": "usr_2b8e4d4a5fc9f3a1",
"message": "Signup successful. Check your email to verify your account."
}
Response के fields
Field
Type
organizationId
string
userId
string
message
string
Errors
Error responses
400कमज़ोर password
{
"error": {
"code": "BAD_REQUEST",
"message": "password must be at least 10 characters and include an uppercase letter, a lowercase letter, a digit and a symbol",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
409Email पहले से registered है
{
"error": {
"code": "CONFLICT",
"message": "A record with these details already exists.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
429Rate limit पार हो गई
{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded: 60 requests per 60 seconds for this endpoint.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Email/password जोड़ी verify करता है और सफल होने पर एक one-time code email करता है और challengeId लौटाता है। अभी कोई session नहीं बनता - login पूरा करने के लिए code के साथ verify-otp call करें।
{
"error": {
"code": "BAD_REQUEST",
"message": "This code is invalid or has expired.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
429Rate limit पार हो गई
{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded: 60 requests per 60 seconds for this endpoint.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
ध्यान दें
जानने लायक बातें
नोट
Response का Set-Cookie header (ऊपर नहीं दिखाया गया) httpOnly session cookie रखता है; इसके बाद हर password-auth call पर frontend को credentials: "include" भेजना होगा।
मौजूदा session का user पाएँ
Endpoint
GET /v1/auth/password/me
GET/v1/auth/password/meलाइव
मौजूदा session cookie के लिए logged-in user लौटाता है।
उदाहरण
Call करके देखें
curl -X GET "https://api-b2b.stampmitra.in/v1/auth/password/me" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxx"
{
"error": {
"code": "BAD_REQUEST",
"message": "This verification link is invalid or has expired.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Email-verification link दोबारा भेजें
Endpoint
POST /v1/auth/password/resend-verification
POST/v1/auth/password/resend-verificationलाइव
Per-email rate-limited; अगर account मौजूद है और verify नहीं हुआ है तो नया verification email भेजता है।
{
"error": {
"code": "BAD_REQUEST",
"message": "password must be at least 10 characters and include an uppercase letter, a lowercase letter, a digit and a symbol",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Team Management
Email + role देकर member को invite करें
Endpoint
POST /v1/team/invites
POST/v1/team/invitesलाइव
केवल Owner/Admin। एक pending invite बनाता है और accept link email करता है। Per-IP और per-email rate-limited है।
Request
Request के parameters
Request के parameters
Field
Type
विवरण
emailज़रूरी
string
Invitee का email।
roleज़रूरी
string
ADMIN, MEMBER में से एक (invite से OWNER नहीं दिया जा सकता)।
{
"error": {
"code": "FORBIDDEN",
"message": "API key is valid but lacks the required scope for this endpoint.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
429Rate limit पार हो गई
{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded: 60 requests per 60 seconds for this endpoint.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Pending invites की सूची
Endpoint
GET /v1/team/invites
GET/v1/team/invitesलाइव
केवल Owner/Admin।
उदाहरण
Call करके देखें
curl -X GET "https://api-b2b.stampmitra.in/v1/team/invites" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxx"
{
"error": {
"code": "BAD_REQUEST",
"message": "Cannot change the role of the organization's last owner.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
404Resource नहीं मिला
{
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Organization से member हटाएँ
Endpoint
DELETE /v1/team/members/:userId
DELETE/v1/team/members/:userIdलाइव
केवल Owner/Admin। आख़िरी owner को हटाया नहीं जा सकता।
{
"error": {
"code": "BAD_REQUEST",
"message": "Cannot remove the organization's last owner.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
404Resource नहीं मिला
{
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found.",
"requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
}
}
Team invite accept करें
Endpoint
POST /v1/team/invites/:token/accept
POST/v1/team/invites/:token/acceptलाइव
Public endpoint (route level पर auth ज़रूरी नहीं)। अगर caller के पास invited email का active session है तो invite तुरंत attach हो जाता है; वरना यह signup_required लौटाता है ताकि frontend invite token साथ रखकर signup पर route कर सके।
उदाहरण
Call करके देखें
curl -X POST "https://api-b2b.stampmitra.in/v1/team/invites/:token/accept" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxx"