--- title: "DEFINE SECURITY IN RAML · Appnovation" url: "https://www.appnovation.com/insights/define-security-raml" description: "How to describe authentication and security schemes in RAML, the YAML-based RESTful API Modeling Language, with practical examples." --- Article # DEFINE SECURITY IN RAML [![](https://cdn.sanity.io/images/ey850001/production/da0302dfbb6aa5d9c86796146fb34bc30690bc21-68x68.jpg?w=68&auto=format) sibu sibu Mulesoft Developer](/people/sibu-sibu.md) Mar 03, 2016 3 min read ![Appnovation Blog Default Header](https://cdn.sanity.io/images/ey850001/production/9efe1c26d9584ecfb3dfef5a63e698bf4567d305-1440x600.jpg?w=1400&auto=format) RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful or practically-RESTful APIs. RAML isn't strict: for now, it focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, RESTful constraints. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more. Basic Structure, defining Request and response are explained deeply in [RAML 100 (opens in new window)](http://raml.org/node/49) docs. RAML also allows you to define the security that would be used for the API **WHY SECURITY IN RAML?** API’s are defined to expose the data to outside world. Basically accessing the underlying, may be sensitive, data. While accessing the data security is one of the critical pieces that a API designer and developers should keep in mind. Since the data being retrieved by the API could be anything, the security becomes important and increases the confidence on the API. **HOW SECURITY IN RAML?** RAML, as we know is a documentation written as text or when using with Mule we could use the AnyPoint platform to design and mule APIKit to develop the RESTful API’s. Defining security can be divided into two parts, Defining SecuritySchemas and setting security for a resources/resourceType or as a whole. **SecuritySchemas** is an optional element in the RAML root. SecuritySchemas contains the definition of the security that would be used to secure the api and it its method. This element contains the name, description, type, describedBy, queryParameters. Lets take the example below Explaining the example 1. \[-oauth\_2.0\] : this would be the name for the security scheme. This would be used to refer across the RAML when telling about the security of the resource. 2. description : description for the security 3. type: type of security 4. describedBy : what parameters describe the security like headers, queryParams and responses, as to what happens if its invalid 5. settings : where to do for authorization etc. **USAGE** The securedBy attribute of RAML document root may be used to apply security schemes to every method of API. This specifies that all methods in the API (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Applying a security scheme to a method overrides whichever security scheme has been applied to the API as whole. To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the securedBy attribute. The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the securitySchemes property of RAML document root. To indicate that the method may be called without applying any security scheme, the method may be provided with securedBy attribute containing null as array component. [![](https://cdn.sanity.io/images/ey850001/production/da0302dfbb6aa5d9c86796146fb34bc30690bc21-68x68.jpg?w=68&auto=format) sibu sibu Mulesoft Developer · Appnovation](/people/sibu-sibu.md) ## Keep reading [![What is Sovereign AI](https://cdn.sanity.io/images/ey850001/production/a5889abdd5e80376912546622e046e3fbef234b4-2496x1664.png?w=640&auto=format)](/insights/what-is-open-source-sovereign-ai.md) Article · 7 min AI ### [What Is Open Source, Sovereign AI?](/insights/what-is-open-source-sovereign-ai.md) Every company is encouraging more AI, and almost every AI bill is climbing. Sovereign AI is about two kinds of control: over your data and over your costs. Here's why open source sits at its foundation. [Iain MacNeil](/people/iain-macneil.md) Article [![AI-first experience design](https://cdn.sanity.io/images/ey850001/production/8bbc2418e87924ef10f36115478a2e10d5bed95e-1584x624.jpg?w=640&auto=format)](/insights/how-build-ai-first-experience-without-throwing-out-everything-youve-already-built.md) Article · 6 min AI Sep 10, 2026 ### [How to Build an AI-First Experience Without Throwing Out Everything You've Already Built](/insights/how-build-ai-first-experience-without-throwing-out-everything-youve-already-built.md) Users now expect a direct answer, not a list of links to click through. Here's how organizations can layer an AI-First experience onto their existing website or app, in weeks rather than years. [Andrew Douglas](/people/andrew-douglas.md) Article [![What Becomes Possible When AI Can Read All the Data](https://cdn.sanity.io/images/ey850001/production/c28ab0bd26753421ee42937e13adc7a7f19b47f0-1296x510.jpg?w=640&auto=format)](/insights/what-becomes-possible-when-ai-can-read-all-data.md) Article · 4 min AI Sep 09, 2026 ### [What Becomes Possible When AI Can Read All the Data](/insights/what-becomes-possible-when-ai-can-read-all-data.md) Most of the world's data has never been analyzed, only sampled. AI changes that. How AI-ready data platforms unlock questions no one could ask before. [Appnovation](/people/appnovation.md) Article ## Get the thinking, *before everyone else.* One considered email a month. New essays, field notes from live engagements, and the occasional strong opinion. No noise.