Version: 0.8.0

ESP RainMaker Neo Auth & Accounts API

Sign-in and account management for the ESP RainMaker Neo cloud. Anything that produces or rotates an access token lives here; once you have a token, the rest of the platform lives in the ESP RainMaker Neo Platform API

ESP User is the platform's own OAuth 2.1 / OIDC issuer: every token a client holds is minted here, regardless of how the user proved their identity. Admins authenticate directly against their AWS Cognito user pool.

Login methods (all end in OUR tokens; upstream credentials never reach clients):

• Federated login (default): GET /oauth2/authorize starts a browser authorization-code + PKCE flow. With a single enabled identity provider the user is auto-redirected to it; the broker exchanges the upstream code server-side and issues OUR authorization code at the client's redirect_uri.
• Native password APIs (/v1/user/auth/*): the main-era native surface. Credentials are verified against the bundled Cognito pool server-side and converted to our tokens.

Token lifecycle after login:

1. POST /oauth2/token (grant_type=refresh_token) - rotate the token set (native /v1/user/auth/token/refresh is reuse-tolerant instead).
2. Send access_token as a Bearer Authorization header on subsequent calls. To call the platform API you must first exchange the token for AWS credentials at POST /v1/user/credentials and SigV4-sign every request. A token this IdP issued is exchanged on its own; a token issued directly by the Cognito provider must also carry its id_token in the body, and the two must come from the same sign-in.

Authentication

API Key: CognitoAuthorizer

Admin Cognito User Pool JWT, for the superadmin APIs (/v1/admin/*). End-user routes take an ESP User token instead — see bearerAuth.

Security Scheme Type:	apiKey
Header parameter name:	Authorization

HTTP: Bearer Auth

An ESP User access token, sent as a Bearer token. The token is verified against the provider's published public keys.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

HTTP: Basic Auth

OAuth client authentication (RFC 6749 §2.3.1) as HTTP Basic base64(client_id:client_secret). A confidential client sends its secret; a public client sends its client_id with an empty secret.

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

Contact

esp-rainmaker-support@espressif.com

URL: https://rainmaker.espressif.com

Terms of Service

http://swagger.io/terms/

License

Apache 2.0