Moov API (v1)

Download OpenAPI specification:Download

The Moov API is an HTTP API served by Moov Financial, Inc for initiating money movements across the ACH payment rail. We follow RESTful operations and naming conventions with predictable and standard HTTP status codes. We are available to help with onboarding or issues related to our services on the Moov slack organization or via support email.

Tenants and Organizations

The Moov API offers grouping for Customer, Transfer, and other records. A Tenant is the largest grouping which covers an entire business entity such as an LCC or corporation. Login credentials are tied to a Tenant and is extracted from the credentials provided on each request. An Organization is a company onboarded by a Tenant that facilitates payments with its Customers.

API requests need an X-Organization header included to properly organize models into their groupings.

Errors

The API will respond with various standard HTTP status codes for errors which indicate how to resolve the request's problem. All errors will be in the application/json Content-Type with the below structure.

{
  "error": "Descriptive message"
}
Status Code Summary Description
200 OK The request was successful.
400 Bad Request The request could not be understood by the server. The Incoming parameters might not be valid.
404 Not Found The requested resource is not found or the credentials are not authorized to access it.
422 Unprocessable Entity The request was parsed but failed validation.
429 Too Many Requests Too many requests have been made in a short period of time. Please make requests at a slower rate or contact us.
500 Server Error The server could not return the representation due to an internal server error.
501 Not Implemented The requested operation is not supported (e.g. supports PUT but not POST etc.)

Access

Currently the Moov API supports authenticaiton with Cookies or JWT's on each request. Those need to be properly created from browser flows or API keys.

OpenID Connect (OIDC) Setup

The Moov API offers one authorization method via a configured OpenID Connect (OIDC) provider for your Tenant. This provider can be Google, Github, LDAP, or another vendor. We leverage OIDC because it allows immediate credential revocation, two-factor verification with that provider and a faster signup flow for users.

Cross-Origin Request Sharing

We support cross-origin resource sharing with whitelisted domains. This allows you to interact securely with our API from client-side web applications. Never expose your secret API key in any public website's client-side code.

Audience Claims

Audience claims are attached onto your JWT request and are used to establish request URIs that the token is authorized to access. They're useful to restrict a specific token to specific access patterns which limits fallout if the token is leaked or stolen.

Within Moov our audience claims do not contain version paths. They are designed to work across endpoint versions.

An example claim requesting a sub-path looks like the following:

get.https://api.moov.io/customers/*

This would allow the following

  • GET https://api.moov.io/v1/customers/e035b3cdfd072f0

but reject the following

  • GET https://api.moov.io/v1/customers/e035b3cdfd072f0/accounts/c20c057bf89d7f5
  • GET https://api.moov.io/v1/transfers
  • DELETE https://api.moov.io/v1/customers/e035b3cdfd072f0/accounts/c20c057bf89d7f5

Note: Multiple HTTP request verbs can be included in an audience claim, for example.

get.post.https://api.moov.io/customers/*/accounts

Note: When creating a JWT include multiple audience claims for all the request URIs to access.

Query parameters

Within an audience claim you can specify whitelisted query parameters. By default no query parameters can be included.

get.https://api.moov.io/transfers?status=*&skip=*&count=*

This would allow the following

  • GET https://api.moov.io/transfers?count=100status=pending&skip=0 (out of order query parameters are allowed)

but reject the following

  • GET https://api.moov.io/transfers?status=pending (missing skip and count)
  • GET https://api.moov.io/transfers?status=pending&skip=0&count=100&extra=false (unexpected extra parameter)

Note: Specified query parameter values are case insensitive when compared to request URIs.

Formatting

Content-Type

All requests and responses will be in the application/json MIME Content-Type unless otherwise specified.

Versioning

The Moov API is currently using /v1/ as the versioning prefix for all endpoints. This results in a base URI of https://api.moov.io/v1/.

Clients

Currently Moov offers a generated Go client for usage with our API. We are looking to support other languages. Please contact us with feedback or suggestions.

Security

Moov continuously monitors and scans our API services for security and privacy issues, but if you find a security related problem please contact us at security@moov.io.

Authentication

GatewayAuth

JWT that comes from the gateway that validates against the gateways public RSA key

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

LoginAuth

Security Scheme Type API Key
Cookie parameter name: moov-authn

Authentication

Check Key

Checks if the specified key is authorized

Request Body schema: application/json
accessToken
string <JWT>
origin
string <url> Nullable
referer
string <url> Nullable
xForwardedFor
string Nullable

Responses

Request samples

Content type
application/json
{
  • "accessToken": "string",
  • "origin": "string",
  • "referer": "string",
  • "xForwardedFor": "string"
}

Response samples

Content type
application/json
{
  • "requestID": "e4619679-f5d9-4eff-9f79-bbded6130bb1",
  • "keyID": "467856bb-692b-416a-b310-660254952741",
  • "tenantID": "f95ac700-4c8f-4a38-a8d1-1582733edd5b",
  • "identity": "10a80a7a-1a32-4a74-b592-aa2a4ef691c5",
  • "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
  • "customer": "0ac6320b-fa4d-4235-8d23-413a2b863bad",
  • "audience": [
    ],
  • "origin": "string",
  • "cidrs": "127.0.0.1/32, 192.168.0.0/16, 10.0.0.0/8",
  • "ip": "string"
}

Finish OIDC Login

Complete a login via a OIDC. Once the OIDC client service has authenticated their identity the client service redirect to this endpoint.

Authorizations:

Responses