Register an OAuth client

Every third-party application identifies itself to the SplashMe API with an OAuth2 client. Registration is self-service: any SplashMe account can create up to 10 clients, and each client belongs to the account that created it.

1. Get a token for your own account

Client management endpoints need a bearer token, and you do not have a client yet. Sign in directly with your SplashMe account credentials:

POST/api-gateway/v1/auth/login

{ "email": "you@example.com", "password": "your-password" }

{
  "status": "SUCCESS",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": { "email": "you@example.com", "firstName": "Sam", "lastName": "Lee", "userId": "aB3dE5fG7h" }
  }
}

The token is valid for 24 hours. This endpoint is limited to 10 attempts per minute per IP address.

2. Create the client

POST/api-gateway/v1/oauth/clients

Authorization: Bearer <token from step 1>
Content-Type: application/json

{
  "name": "My Pool App",
  "allowed_redirect_uris": [
    "https://app.example.com/oauth/callback",
    "http://localhost:3000/oauth/callback"
  ]
}

Response, 201 Created:

{
  "status": "SUCCESS",
  "data": {
    "client": {
      "name": "My Pool App",
      "client_id": "sm_ab3de5fg7h_my-pool-app",
      "client_secret": "sm_secret_0123456789abcdef0123456789abcdef",
      "allowed_redirect_uris": ["https://app.example.com/oauth/callback", "http://localhost:3000/oauth/callback"]
    },
    "current_count": 1,
    "max_count": 10
  }
}

Store client_id and client_secret in your server-side configuration. The secret must never ship inside a mobile or browser application.

Redirect URI rules

• Each URI must be absolute, with a scheme and a host. http://localhost:3000/cb is accepted for development.
• At authorization time the redirect_uri you send must match one of the registered values exactly, character for character. There is no prefix or wildcard matching.
• Blank entries are dropped and duplicates are removed. At least one URI is required.

Errors

Status	message	Cause
400	name and allowed_redirect_uris are required	Missing field
400	client name already exists	You already have a client with that name
400	OAuth client limit reached (10)	Delete an unused client first
400	redirect_uri must include scheme and host: <value>	Relative URI
400	invalid redirect_uri: <value>	URI that cannot be parsed
400	at least one redirect_uri is required	All entries were blank
400	name is required	Name was blank
401	User not found	The token’s account no longer exists
401	Invalid token	Token expired or malformed

Managing clients

See Client management for listing and deleting clients.